HybridDeviceTagger.Management.psm1
|
#Requires -Version 7.2 # Project-Version: 202611.3 # Author: andreas.lucas@outlook.com (aka Kili) <# Copyright 2026 Andreas Lucas Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. SPDX-License-Identifier: Apache-2.0 #> <# .SYNOPSIS PowerShell client for the Entra-protected HybridDeviceTagger management API. .DESCRIPTION The module maintains one connection per PowerShell module instance. Connect-HybridDeviceTagger initializes that connection from the current Azure CLI sign-in. All other exported commands reuse the connection and refresh its delegated access token shortly before expiry. Read commands return structured objects. Write and action commands use PowerShell ShouldProcess; destructive or security-sensitive commands additionally use high-impact confirmation. Collection updates send the latest API ETag in If-Match so concurrent changes fail instead of being overwritten. The module does not require direct access to Active Directory, Key Vault, Blob Storage, Microsoft Graph, or Azure Resource Manager. Those operations are performed by the Function App after the management API has authorized the caller. .NOTES Requires PowerShell 7.2 or later, Azure CLI, an existing az login session, and network access to the Function App. Importing the module does not authenticate or make a network request. The connection and access token exist only in module scope for the current PowerShell process. Disconnect by removing the module or closing the PowerShell session. .LINK https://github.com/Kili69/HybridDeviceTagger #> Set-StrictMode -Version Latest # Shared only by commands in this module instance; never persisted and cleared after failed validation. $script:Connection = $null <# .SYNOPSIS Acquires or refreshes the delegated management API access token. .DESCRIPTION Calls Azure CLI for the api://<client-id>/.default scope and stores the token and normalized expiry on the module-scoped connection. Both Azure CLI expiry formats are supported. If Azure CLI omits an expiry, a conservative five-minute lifetime forces an early refresh on the next request. .OUTPUTS None. .NOTES Private module function. It requires an initialized connection and never writes the token to the success stream. #> function Initialize-HybridDeviceTaggerToken { # Fail before accessing the connection when the external authentication dependency is unavailable. if (-not (Get-Command az -CommandType Application -ErrorAction SilentlyContinue)) { throw 'Azure CLI is required. Install Azure CLI, run az login, and try again.' } # The .default scope requests the delegated permissions already consented for this API audience. $tokenResponse = az account get-access-token ` --scope "api://$($script:Connection.ClientId)/.default" ` --output json ` --only-show-errors | ConvertFrom-Json # Azure CLI failures and malformed success responses are both unusable authentication results. if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace([string]$tokenResponse.accessToken)) { throw "Unable to obtain an Entra access token for api://$($script:Connection.ClientId). Run 'az login --scope api://$($script:Connection.ClientId)/.default' and try again." } $script:Connection.AccessToken = [string]$tokenResponse.accessToken # Azure CLI versions expose either Unix seconds or a formatted date. Normalize both representations. $script:Connection.ExpiresOn = if ($tokenResponse.PSObject.Properties['expires_on']) { [DateTimeOffset]::FromUnixTimeSeconds([long]$tokenResponse.expires_on) } elseif ($tokenResponse.PSObject.Properties['expiresOn']) { [DateTimeOffset]::Parse( [string]$tokenResponse.expiresOn, [Globalization.CultureInfo]::InvariantCulture) } else { # Unknown expiry is deliberately short-lived and never creates an indefinitely valid session. [DateTimeOffset]::UtcNow.AddMinutes(5) } } <# .SYNOPSIS Ensures that a usable management API connection and access token exist. .DESCRIPTION Rejects commands executed before Connect-HybridDeviceTagger and refreshes the delegated token when it is missing or expires within two minutes. The refresh margin prevents expiry during an API call. .OUTPUTS None. .NOTES Private module function. #> function Assert-HybridDeviceTaggerConnection { # Public operations cannot infer the deployment or token audience without an explicit connection. if ($null -eq $script:Connection) { throw 'No HybridDeviceTagger API connection exists. Run Connect-HybridDeviceTagger first.' } # Refresh two minutes early to cover request latency and synchronous management operations. if ([string]::IsNullOrWhiteSpace($script:Connection.AccessToken) -or $script:Connection.ExpiresOn -le [DateTimeOffset]::UtcNow.AddMinutes(2)) { Initialize-HybridDeviceTaggerToken } } <# .SYNOPSIS Sends one authenticated request to the HybridDeviceTagger management API. .DESCRIPTION Builds the endpoint URI from the active connection, serializes optional request bodies as JSON, adds an optional If-Match header, and translates REST failures into terminating errors with the method and relative path. .PARAMETER Method Specifies the supported HTTP method. .PARAMETER Path Specifies the API path relative to the configured base URI. .PARAMETER Body Specifies an optional object serialized as UTF-8 JSON with a maximum depth of 20. .PARAMETER ETag Specifies an optional entity tag used for optimistic concurrency through If-Match. .PARAMETER IncludeResponseHeaders Returns an envelope containing response content and the response ETag. .OUTPUTS The deserialized API response, or an object with Content and ETag when response headers are requested. .NOTES Private module function. API failures remain terminating errors so automation cannot interpret a failed operation as success. #> function Invoke-HybridDeviceTaggerRequest { param( [Parameter(Mandatory)][ValidateSet('Get', 'Put', 'Post', 'Delete')][string]$Method, [Parameter(Mandatory)][ValidateNotNullOrEmpty()][string]$Path, [AllowNull()][object]$Body, [AllowNull()][string]$ETag, [switch]$IncludeResponseHeaders ) # Authentication state is checked for every request, not only when the connection is created. Assert-HybridDeviceTaggerConnection $headers = @{ Authorization = "Bearer $($script:Connection.AccessToken)" } if (-not [string]::IsNullOrWhiteSpace($ETag)) { # If-Match turns collection writes into optimistic-concurrency operations. $headers['If-Match'] = $ETag } # Normalize the relative path to one separator without changing the configured management base path. $parameters = @{ Method = $Method Uri = "$($script:Connection.ApiBaseUri)/$($Path.TrimStart('/'))" Headers = $headers } if ($PSBoundParameters.ContainsKey('Body')) { # Depth 20 preserves nested rules, arrays, and extension-attribute dictionaries. $parameters.ContentType = 'application/json; charset=utf-8' $parameters.Body = ConvertTo-Json -InputObject $Body -Depth 20 -Compress } if ($IncludeResponseHeaders) { # Invoke-RestMethod assigns the response headers to this local variable after completion. $parameters.ResponseHeadersVariable = 'responseHeaders' } try { $result = Invoke-RestMethod @parameters } catch { # Add endpoint context and preserve a terminating failure for scripts and deployment pipelines. throw "HybridDeviceTagger API request '$Method $Path' failed: $($_.Exception.Message)" } if ($IncludeResponseHeaders) { # Snapshot callers need the resource and its version from the same HTTP response. return [pscustomobject]@{ Content = $result ETag = [string]$responseHeaders['ETag'] } } $result } <# .SYNOPSIS Gets the tagging configuration and its current ETag. .OUTPUTS An object with Content and ETag properties. .NOTES Private module function used immediately before ETag-protected rule changes. #> function Get-HybridDeviceTaggerConfigurationSnapshot { # Centralized snapshot acquisition ensures every rule mutation receives the current response ETag. Invoke-HybridDeviceTaggerRequest -Method Get -Path 'tagging-rules' -IncludeResponseHeaders } <# .SYNOPSIS Polls the status endpoint until a queued operation has finished. .DESCRIPTION Polls every 10 seconds. The run belongs to the request only while the status reports the same invocation ID; a different ID means a newer run replaced the status, which is reported as an error. .PARAMETER Operation The operation status route, device-tagging or password-rotation. .PARAMETER InvocationId The invocation ID returned when the request was accepted. .PARAMETER TimeoutSeconds The maximum polling time. .OUTPUTS System.Management.Automation.PSCustomObject containing the final operation status. .NOTES Private module function used by the -Wait switch of the action commands. #> function Wait-HybridDeviceTaggerOperation { param( [Parameter(Mandatory)][ValidateSet('device-tagging', 'password-rotation')][string]$Operation, [Parameter(Mandatory)][string]$InvocationId, [Parameter(Mandatory)][int]$TimeoutSeconds ) $deadline = [DateTimeOffset]::UtcNow.AddSeconds($TimeoutSeconds) while ($true) { $status = Invoke-HybridDeviceTaggerRequest -Method Get -Path "status/$Operation" if ([string]$status.invocationId -ne $InvocationId) { throw "The $Operation request '$InvocationId' was superseded by invocation '$($status.invocationId)'. Check the status and retry if required." } if ([string]$status.state -in @('Succeeded', 'Failed')) { return $status } if ([DateTimeOffset]::UtcNow -ge $deadline) { throw "The $Operation request '$InvocationId' did not finish within $TimeoutSeconds seconds. Its current state is '$($status.state)'." } Start-Sleep -Seconds 10 } } <# .SYNOPSIS Connects the current PowerShell session to the HybridDeviceTagger management API. .DESCRIPTION Uses the existing Azure CLI sign-in to acquire a delegated Microsoft Entra access token and stores the API URI, token audience, token, and expiry in module scope. All other module cmdlets reuse this connection. By default, the command validates the connection by reading the tagging configuration. .PARAMETER ApiBaseUri Specifies the absolute HTTPS URI of the management API, including the /api/management path. .PARAMETER ClientId Specifies the non-secret Microsoft Entra application client ID used as the access-token audience. .PARAMETER SkipValidation Stores the connection without making the initial tagging-configuration request. .PARAMETER PassThru Returns non-sensitive connection information. The access token is never included. .OUTPUTS HybridDeviceTagger.Management.ConnectionInfo when PassThru is specified. Otherwise, no output. .EXAMPLE Connect-HybridDeviceTagger Connects to the production management API using the existing Azure CLI sign-in. .EXAMPLE Connect-HybridDeviceTagger -ApiBaseUri 'https://example.azurewebsites.net/api/management' -ClientId $clientId -PassThru Connects to another deployment and returns its non-sensitive connection information. #> function Connect-HybridDeviceTagger { [CmdletBinding()] param( [uri]$ApiBaseUri = 'https://func-hybriddevicetagger.azurewebsites.net/api/management', [ValidatePattern('^[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$')] [string]$ClientId = '5e324803-5aed-4e5d-b49f-a4bfceddcda8', [switch]$SkipValidation, [switch]$PassThru ) # Reject relative and unencrypted endpoints before creating authentication state. if (-not $ApiBaseUri.IsAbsoluteUri -or $ApiBaseUri.Scheme -ne 'https') { throw 'ApiBaseUri must be an absolute HTTPS URI.' } # Normalize the base URI and initialize the token fields before the first acquisition. $script:Connection = [pscustomobject]@{ PSTypeName = 'HybridDeviceTagger.Management.Connection' ApiBaseUri = $ApiBaseUri.AbsoluteUri.TrimEnd('/') ClientId = $ClientId AccessToken = $null ExpiresOn = [DateTimeOffset]::MinValue } try { # Authenticate eagerly so Connect reports authentication problems immediately. Initialize-HybridDeviceTaggerToken if (-not $SkipValidation) { # This read validates reachability, token audience, Easy Auth, and caller authorization. $null = Get-HybridDeviceTaggerConfigurationSnapshot } } catch { # A failed token request or validation read must not leave a partial connection behind. $script:Connection = $null throw } if ($PassThru) { # Explicit projection guarantees that the access token cannot enter the success pipeline. [pscustomobject]@{ PSTypeName = 'HybridDeviceTagger.Management.ConnectionInfo' ApiBaseUri = $script:Connection.ApiBaseUri ClientId = $script:Connection.ClientId ExpiresOn = $script:Connection.ExpiresOn } } } <# .SYNOPSIS Gets HybridDeviceTagger tagging rules. .DESCRIPTION Reads the effective tagging configuration through the connected management API. Without Name, the command emits every rule. With Name, it emits rules whose names match case-insensitively. .PARAMETER Name Specifies an optional rule name to retrieve. Matching is case-insensitive. .OUTPUTS System.Management.Automation.PSCustomObject. One object is emitted for each matching rule. .EXAMPLE Get-HybridDeviceTaggerRule Returns all effective tagging rules. .EXAMPLE Get-HybridDeviceTaggerRule -Name 'Kiosk devices' Returns the named rule when it exists. #> function Get-HybridDeviceTaggerRule { [CmdletBinding()] param( [Parameter(Position = 0)] [ValidateLength(1, 128)] [string]$Name ) # The common snapshot helper also gives this read the same response-shape handling as writes. $snapshot = Get-HybridDeviceTaggerConfigurationSnapshot # Array coercion provides stable zero-, one-, or many-object pipeline behavior. $rules = @($snapshot.Content.rules) if ($PSBoundParameters.ContainsKey('Name')) { # Parameter presence controls filtering; ValidateLength already rejects an empty supplied name. $rules | Where-Object { $_.name -ieq $Name } } else { $rules } } <# .SYNOPSIS Gets the status of the latest device-tagging run. .DESCRIPTION Returns the persisted state, invocation ID, timestamps, result counters, and sanitized failure information for the latest scheduled or manually triggered device-tagging run. .OUTPUTS System.Management.Automation.PSCustomObject. .EXAMPLE Get-HybridDeviceTaggerLastRunStatus | Format-List Displays all properties of the latest device-tagging status. #> function Get-HybridDeviceTaggerLastRunStatus { [CmdletBinding()] param() # Return the persisted API document unchanged so future server fields remain available to callers. Invoke-HybridDeviceTaggerRequest -Method Get -Path 'status/device-tagging' } <# .SYNOPSIS Gets the status of the latest password-rotation operation. .DESCRIPTION Returns the latest password-rotation check state and the timestamp of the last actual service-account password change. The response contains operational metadata but never contains a password. .OUTPUTS System.Management.Automation.PSCustomObject. .EXAMPLE Get-HybridDeviceTaggerPasswordRotationStatus | Format-List Displays the latest password-rotation status and last password-change timestamp. #> function Get-HybridDeviceTaggerPasswordRotationStatus { [CmdletBinding()] param() # The endpoint exposes operational metadata only and never returns current or staged passwords. Invoke-HybridDeviceTaggerRequest -Method Get -Path 'status/password-rotation' } <# .SYNOPSIS Gets the latest device-tagging trace as structured events. .DESCRIPTION Downloads and parses the latest JSONL trace. Each event is emitted as a HybridDeviceTagger.TraceEvent object. The default screen view is one logical line in the format time,severity,phase,status,action,details, while pipeline operations retain every event property. .OUTPUTS HybridDeviceTagger.TraceEvent. One object is emitted for each JSONL trace event. .EXAMPLE Get-HybridDeviceTaggerTrace Displays the latest trace using the concise one-line event view. .EXAMPLE $errors = @(Get-HybridDeviceTaggerTrace | Where-Object level -eq 'Error') Stores only error events as structured objects. .EXAMPLE Get-HybridDeviceTaggerTrace | Select-Object timestampUtc, action, details | Export-Csv ./trace.csv Exports selected structured trace properties to a CSV file. #> function Get-HybridDeviceTaggerTrace { [CmdletBinding()] param() # JSONL contains one independent JSON object per line, rather than one enclosing JSON array. $content = Invoke-HybridDeviceTaggerRequest -Method Get -Path 'traces/device-tagging/latest' foreach ($line in $content -split "`r?`n") { if (-not [string]::IsNullOrWhiteSpace($line)) { $traceEvent = $line | ConvertFrom-Json # Select the concise module view without flattening the object returned to the pipeline. $traceEvent.PSObject.TypeNames.Insert(0, 'HybridDeviceTagger.TraceEvent') $traceEvent } } } <# .SYNOPSIS Adds or replaces one or more named HybridDeviceTagger rules. .DESCRIPTION Accepts either one complete rule or an object with a Rules property. Each rule is sent separately to the management API. A rule with the same case-insensitive name is completely replaced; other rules are preserved. .PARAMETER Rule Specifies one complete rule object or an object whose Rules property contains up to 100 complete rules. Each rule must contain Name, Description, BaseDn, ExtensionAttributes, EntraGroupIds, and AdministrativeUnitIds as required by the management API. .OUTPUTS System.Management.Automation.PSCustomObject representing the persisted configuration when applied. .EXAMPLE $rule = @{ name = 'Kiosk devices' description = 'Tags devices located in the kiosk OU.' baseDn = 'OU=Kiosks,OU=Workstations' extensionAttributes = @{ extensionAttribute1 = 'Kiosk' } entraGroupIds = @() administrativeUnitIds = @() } Add-HybridDeviceTaggerRule -Rule $rule -WhatIf Previews adding or replacing the Kiosk devices rule. .EXAMPLE $rule | Add-HybridDeviceTaggerRule Adds or replaces a complete rule received from the pipeline. .EXAMPLE $configuration = @{ Rules = @($kioskRule, $workstationRule) } Add-HybridDeviceTaggerRule -Rule $configuration Adds or replaces every rule in the Rules property while preserving all other existing rules. #> function Add-HybridDeviceTaggerRule { [CmdletBinding(SupportsShouldProcess)] param( [Parameter(Mandatory, ValueFromPipeline)][ValidateNotNull()][object]$Rule ) process { # Accept one rule or an exported configuration with a case-insensitive Rules property. $rulesProperty = $null if ($Rule -is [System.Collections.IDictionary]) { # Hashtable keys do not participate in PSObject property lookup, so inspect keys explicitly. $rulesKey = $Rule.Keys | Where-Object { [string]$_ -ieq 'Rules' } | Select-Object -First 1 if ($null -ne $rulesKey) { $rulesProperty = $Rule[$rulesKey] } } else { # PSCustomObject and deserialized JSON input expose Rules through the property collection. $property = $Rule.PSObject.Properties | Where-Object Name -IEQ 'Rules' | Select-Object -First 1 if ($null -ne $property) { $rulesProperty = $property.Value } } # A plain rule becomes a one-item batch; a configuration wrapper contributes its Rules collection. $rules = if ($null -ne $rulesProperty) { @($rulesProperty) } else { @($Rule) } if ($rules.Count -lt 1 -or $rules.Count -gt 100) { throw 'Rules must contain between 1 and 100 rule objects.' } foreach ($candidateRule in $rules) { # Only the routing key is checked locally; the API remains authoritative for the full schema. $name = [string]$candidateRule.name if ([string]::IsNullOrWhiteSpace($name)) { throw 'Each rule must contain a non-empty Name property.' } # Every successful upsert changes the collection ETag, so refresh for each rule. $snapshot = Get-HybridDeviceTaggerConfigurationSnapshot if ($PSCmdlet.ShouldProcess($name, 'Add or replace HybridDeviceTagger tagging rule')) { Invoke-HybridDeviceTaggerRequest ` -Method Put ` -Path "tagging-rules/$([uri]::EscapeDataString($name))" ` -Body $candidateRule ` -ETag $snapshot.ETag } } } } <# .SYNOPSIS Removes one named HybridDeviceTagger rule. .DESCRIPTION Reads the latest configuration ETag and removes the case-insensitively matching rule through the management API. The API rejects a result that would leave no valid tagging rules. .PARAMETER Name Specifies the unique rule name to remove. Matching is case-insensitive. .OUTPUTS System.Management.Automation.PSCustomObject representing the persisted configuration when applied. .EXAMPLE Remove-HybridDeviceTaggerRule -Name 'Kiosk devices' -WhatIf Previews removal of the named rule. .EXAMPLE Remove-HybridDeviceTaggerRule -Name 'Kiosk devices' -Confirm Removes the named rule after confirmation. #> function Remove-HybridDeviceTaggerRule { [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] param( [Parameter(Mandatory, Position = 0)][ValidateLength(1, 128)][string]$Name ) # Couple the delete to the configuration version presented before user confirmation. $snapshot = Get-HybridDeviceTaggerConfigurationSnapshot if ($PSCmdlet.ShouldProcess($Name, 'Remove HybridDeviceTagger tagging rule')) { # URI escaping keeps valid rule names with spaces or reserved characters in one route segment. Invoke-HybridDeviceTaggerRequest ` -Method Delete ` -Path "tagging-rules/$([uri]::EscapeDataString($Name))" ` -ETag $snapshot.ETag } } <# .SYNOPSIS Starts device tagging immediately. .DESCRIPTION Queues the same device-tagging orchestration used by the timer and returns the accepted request with its invocation ID. The API returns a conflict when another tagging run is active. Use Wait to poll the status endpoint until the requested run has finished. .PARAMETER Wait Waits for the queued run to finish and returns its final status. .PARAMETER TimeoutSeconds Specifies how long Wait polls before failing. The default is 1,800 seconds. .OUTPUTS System.Management.Automation.PSCustomObject containing invocationId, state, and statusUri, or the final operation status when Wait is specified. .EXAMPLE Invoke-HybridDeviceTagging -WhatIf Shows the target operation without queuing device tagging. .EXAMPLE $status = Invoke-HybridDeviceTagging -Wait Runs device tagging and returns the final status including the aggregate result. #> function Invoke-HybridDeviceTagging { [CmdletBinding(SupportsShouldProcess)] param( [switch]$Wait, [ValidateRange(30, 86400)] [int]$TimeoutSeconds = 1800 ) # Validate before ShouldProcess so the confirmation target always refers to an active connection. Assert-HybridDeviceTaggerConnection if ($PSCmdlet.ShouldProcess($script:Connection.ApiBaseUri, 'Run device tagging immediately')) { # The action endpoint queues the run and returns HTTP 202 with its invocation ID. $accepted = Invoke-HybridDeviceTaggerRequest -Method Post -Path 'actions/device-tagging' if (-not $Wait) { return $accepted } Wait-HybridDeviceTaggerOperation ` -Operation 'device-tagging' ` -InvocationId ([string]$accepted.invocationId) ` -TimeoutSeconds $TimeoutSeconds } } <# .SYNOPSIS Gets the effective Active Directory forest-domain configuration. .DESCRIPTION Reads the stored forest domain or its initial application setting without contacting Active Directory. Requires Reader, RuleAdministrator, PasswordRotationAdministrator, or effective Function App Owner/Contributor access. .OUTPUTS System.Management.Automation.PSCustomObject containing domain, eTag, lastModifiedUtc, and source. .EXAMPLE Get-HybridDeviceTaggerActiveDirectoryConfiguration #> function Get-HybridDeviceTaggerActiveDirectoryConfiguration { [CmdletBinding()] param() Invoke-HybridDeviceTaggerRequest -Method Get -Path 'active-directory' } <# .SYNOPSIS Changes the Active Directory forest DNS domain used by the Function. .DESCRIPTION Validates the DNS-name syntax and persists the domain without requiring working AD DNS, LDAP, or an initialized credential. New forest connections read the change without restarting the Function. Existing runs can finish using their previous domain. Requires effective Function App Owner/Contributor access, because the domain selects the servers that receive the service-account password; management API application roles are not sufficient. .PARAMETER Domain The forest DNS name, not a domain-controller name or the _ldap SRV record name. .OUTPUTS System.Management.Automation.PSCustomObject containing the stored configuration and ETag. .EXAMPLE Set-HybridDeviceTaggerActiveDirectoryConfiguration -Domain 'contoso.com' -Confirm #> function Set-HybridDeviceTaggerActiveDirectoryConfiguration { [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] param( [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [string]$Domain ) Assert-HybridDeviceTaggerConnection if ($PSCmdlet.ShouldProcess($script:Connection.ApiBaseUri, "Set Active Directory forest domain to '$Domain'")) { $snapshot = Invoke-HybridDeviceTaggerRequest -Method Get -Path 'active-directory' -IncludeResponseHeaders Invoke-HybridDeviceTaggerRequest -Method Put -Path 'active-directory' ` -Body @{ domain = $Domain } -ETag $snapshot.ETag } } <# .SYNOPSIS Sets the Active Directory service account and its current password. .DESCRIPTION Sends the UPN, password, and optional distinguished name to the Function App. The Function binds to Active Directory with the credential through LDAPS or StartTLS, stores the password in Key Vault through its managed identity, and then stores the account. The forest domain and a trust certificate must be configured first. Replaces an existing account or password, so it also serves as the post-installation credential initialization. Requires effective Function App Owner/Contributor access. .PARAMETER Credential The service-account UPN and its current password. .PARAMETER DistinguishedName Optional distinguished name of the account. When omitted, the Function resolves it from the UPN. .OUTPUTS System.Management.Automation.PSCustomObject containing username, distinguishedName, and eTag. .EXAMPLE Set-HybridDeviceTaggerServiceAccount -Credential (Get-Credential 'svc-tagger@contoso.com') -Confirm #> function Set-HybridDeviceTaggerServiceAccount { [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] param( [Parameter(Mandatory)] [ValidateNotNull()] [pscredential]$Credential, [ValidateNotNullOrEmpty()] [ValidateLength(1, 1024)] [string]$DistinguishedName ) if ($Credential.UserName -notmatch '^[^@\s\\]+@[^@\s]+\.[^@\s]+$') { throw 'Credential.UserName must be a user principal name such as svc-tagger@contoso.com.' } Assert-HybridDeviceTaggerConnection if ($PSCmdlet.ShouldProcess( $script:Connection.ApiBaseUri, "Validate and store Active Directory service account '$($Credential.UserName)'")) { $plainPassword = $Credential.GetNetworkCredential().Password try { Invoke-HybridDeviceTaggerRequest -Method Put -Path 'portal/active-directory/account' -Body @{ username = $Credential.UserName password = $plainPassword distinguishedName = $DistinguishedName } } finally { $plainPassword = $null } } } <# .SYNOPSIS Gets the LDAP trust certificates used by the Function. .DESCRIPTION Returns thumbprint, subject, issuer, validity, and origin of every trust anchor. Requires effective Function App Owner/Contributor access. .OUTPUTS System.Management.Automation.PSCustomObject containing certificates, eTag, and source. .EXAMPLE (Get-HybridDeviceTaggerTrustedCertificate).certificates | Format-Table thumbprint, subject, notAfterUtc #> function Get-HybridDeviceTaggerTrustedCertificate { [CmdletBinding()] param() Invoke-HybridDeviceTaggerRequest -Method Get -Path 'portal/certificates' } <# .SYNOPSIS Adds a public root CA or self-signed domain-controller certificate as LDAP trust anchor. .DESCRIPTION Loads the certificate locally, rejects files containing a private key or expired certificates, and sends only the public PEM to the Function. New LDAP connections use the trust anchor immediately. Requires effective Function App Owner/Contributor access. .PARAMETER Path Path to a DER (.cer/.crt) or PEM certificate file. .OUTPUTS System.Management.Automation.PSCustomObject containing the stored trust anchors. .EXAMPLE Add-HybridDeviceTaggerTrustedCertificate -Path '.\Contoso-Root-CA.cer' -Confirm #> function Add-HybridDeviceTaggerTrustedCertificate { [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] param( [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [string]$Path ) $resolvedPath = (Resolve-Path -LiteralPath $Path -ErrorAction Stop).Path try { $certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($resolvedPath) } catch { throw "'$Path' is not a valid X.509 certificate." } try { if ($certificate.HasPrivateKey) { throw "'$Path' contains a private key. Export only the public certificate." } if ($certificate.NotAfter -le [DateTime]::Now) { throw "Certificate '$($certificate.Thumbprint)' expired on $($certificate.NotAfter)." } Assert-HybridDeviceTaggerConnection if ($PSCmdlet.ShouldProcess( $script:Connection.ApiBaseUri, "Trust LDAP certificate '$($certificate.Subject)' ($($certificate.Thumbprint))")) { Invoke-HybridDeviceTaggerRequest -Method Post -Path 'portal/certificates' ` -Body @{ certificate = $certificate.ExportCertificatePem() } } } finally { $certificate.Dispose() } } <# .SYNOPSIS Removes an LDAP trust certificate. .DESCRIPTION Removes the trust anchor with the specified thumbprint. The last trust anchor cannot be removed. Requires effective Function App Owner/Contributor access. .PARAMETER Thumbprint SHA-1 thumbprint of the certificate to remove. .OUTPUTS System.Management.Automation.PSCustomObject containing the remaining trust anchors. .EXAMPLE Remove-HybridDeviceTaggerTrustedCertificate -Thumbprint 'A1B2...' -Confirm #> function Remove-HybridDeviceTaggerTrustedCertificate { [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] param( [Parameter(Mandatory)] [ValidatePattern('^[0-9a-fA-F]{40}$')] [string]$Thumbprint ) Assert-HybridDeviceTaggerConnection if ($PSCmdlet.ShouldProcess($script:Connection.ApiBaseUri, "Remove LDAP trust certificate '$Thumbprint'")) { Invoke-HybridDeviceTaggerRequest -Method Delete -Path "portal/certificates/$($Thumbprint.ToUpperInvariant())" } } <# .SYNOPSIS Initializes the Active Directory service-account credential through the Function App. .DESCRIPTION Sends the password to the Entra-protected management API. The Function validates the credential against Active Directory and stores it in Key Vault through its managed identity. Initialization fails when the current credential secret already contains a password; only a missing secret or the unusable placeholder created by the installer is replaced. .PARAMETER Password Specifies the initial Active Directory service-account password as a SecureString. .OUTPUTS System.Management.Automation.PSCustomObject confirming successful initialization. .EXAMPLE $password = Read-Host 'AD service-account password' -AsSecureString Initialize-HybridDeviceTaggerActiveDirectoryCredential -Password $password -Confirm Validates and stores the initial credential without granting the operator Key Vault data access. #> function Initialize-HybridDeviceTaggerActiveDirectoryCredential { [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] param( [Parameter(Mandatory)][ValidateNotNull()][Security.SecureString]$Password ) # Establish the HTTPS target before asking permission to transmit the credential. Assert-HybridDeviceTaggerConnection if ($PSCmdlet.ShouldProcess( $script:Connection.ApiBaseUri, 'Validate and initialize the Active Directory service-account credential')) { # Plain text exists only long enough to serialize the protected HTTPS request. $plainPassword = ConvertFrom-SecureString -SecureString $Password -AsPlainText try { # The Function performs AD validation and Key Vault persistence with its own managed identity. Invoke-HybridDeviceTaggerRequest ` -Method Post ` -Path 'actions/initialize-ad-credential' ` -Body @{ password = $plainPassword } } finally { # Remove the module's remaining reference even when serialization or the request fails. $plainPassword = $null } } } <# .SYNOPSIS Forces an immediate Active Directory service-account password rotation. .DESCRIPTION Queues a password rotation that bypasses only the configured password-age threshold. Current credential verification, secure LDAP, Key Vault staging, changed-credential validation, and secret promotion remain mandatory. The operation changes the real service-account password when safe. Use Wait to poll the status endpoint until the requested rotation has finished. .PARAMETER Wait Waits for the queued rotation to finish and returns its final status. .PARAMETER TimeoutSeconds Specifies how long Wait polls before failing. The default is 600 seconds. .OUTPUTS System.Management.Automation.PSCustomObject containing invocationId, state, and statusUri, or the final operation status when Wait is specified. .EXAMPLE Invoke-HybridDeviceTaggerPasswordRotation -WhatIf Shows the target operation without changing the password. .EXAMPLE Invoke-HybridDeviceTaggerPasswordRotation -Wait -Confirm Forces password rotation after high-impact confirmation and waits for the result. #> function Invoke-HybridDeviceTaggerPasswordRotation { [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] param( [switch]$Wait, [ValidateRange(30, 86400)] [int]$TimeoutSeconds = 600 ) # Validate before the high-impact prompt so failures cannot occur after unnecessary confirmation. Assert-HybridDeviceTaggerConnection if ($PSCmdlet.ShouldProcess( $script:Connection.ApiBaseUri, 'Immediately change the Active Directory service-account password')) { # Server-side safeguards still enforce LDAPS, staging, validation, and secret promotion. $accepted = Invoke-HybridDeviceTaggerRequest -Method Post -Path 'actions/password-rotation' if (-not $Wait) { return $accepted } Wait-HybridDeviceTaggerOperation ` -Operation 'password-rotation' ` -InvocationId ([string]$accepted.invocationId) ` -TimeoutSeconds $TimeoutSeconds } } # Export only the supported management surface; authentication and HTTP helpers remain private. Export-ModuleMember -Function @( 'Connect-HybridDeviceTagger', 'Get-HybridDeviceTaggerRule', 'Get-HybridDeviceTaggerLastRunStatus', 'Get-HybridDeviceTaggerPasswordRotationStatus', 'Get-HybridDeviceTaggerTrace', 'Add-HybridDeviceTaggerRule', 'Remove-HybridDeviceTaggerRule', 'Get-HybridDeviceTaggerActiveDirectoryConfiguration', 'Set-HybridDeviceTaggerActiveDirectoryConfiguration', 'Set-HybridDeviceTaggerServiceAccount', 'Get-HybridDeviceTaggerTrustedCertificate', 'Add-HybridDeviceTaggerTrustedCertificate', 'Remove-HybridDeviceTaggerTrustedCertificate', 'Initialize-HybridDeviceTaggerActiveDirectoryCredential', 'Invoke-HybridDeviceTagging', 'Invoke-HybridDeviceTaggerPasswordRotation' ) |