Get odata token

.gitignore

@@ -22,3 +22,4 @@ TestResults/*
 publish/*
 agent-tools
 terminals
+docs/superpowers

d365bap.tools/d365bap.tools.psd1

@@ -93,6 +93,7 @@
 
 		'xml\formats\list\D365Bap.Tools.FscmDmfEntity.List.Format.ps1xml',
 		'xml\formats\list\D365Bap.Tools.FscmOdataEntity.List.Format.ps1xml',
+		'xml\formats\list\D365Bap.Tools.FscmOdataToken.List.Format.ps1xml',
 		'xml\formats\list\D365Bap.Tools.FscmRestService.List.Format.ps1xml',
 		'xml\formats\list\D365Bap.Tools.FscmRole.List.Format.ps1xml',
 
@@ -153,6 +154,7 @@
 		, 'Get-FscmEntraApplication'
 		, 'Get-FscmOdata'
 		, 'Get-FscmOdataEntity'
+		, 'Get-FscmOdataToken'
 		, 'Get-FscmRestService'
 		, 'Get-FscmSecurityRole'
 		, 'Get-FscmSecurityRoleMember'

d365bap.tools/functions/Get-FscmOdataToken.ps1

@@ -0,0 +1,101 @@
+
+<#
+    .SYNOPSIS
+        Get an OData access token for a Finance and Operations environment.
+
+    .DESCRIPTION
+        Acquires an Azure access token scoped to the Finance and Operations (FnO) OData resource of the specified environment, using the cached credentials in the local Azure PowerShell context.
+
+        The token is returned in plain text. Handle the output accordingly.
+
+    .PARAMETER EnvironmentId
+        The ID of the environment to acquire the token for.
+
+        Can be either the environment name, the environment GUID (PPAC) or the LCS environment ID.
+
+    .PARAMETER AsBearerToken
+        Output the token as a "Bearer" prefix string, ready to use in an Authorization header.
+
+    .PARAMETER AsObject
+        Output a typed PSCustomObject with Token and BearerToken properties.
+
+    .EXAMPLE
+        PS C:\> Get-FscmOdataToken -EnvironmentId "ContosoEnv"
+
+        This command acquires an OData access token for the environment "ContosoEnv" and returns the raw token string.
+
+    .EXAMPLE
+        PS C:\> Get-FscmOdataToken -EnvironmentId "ContosoEnv" -AsBearerToken
+
+        This command acquires an OData access token for the environment "ContosoEnv" and returns it as a bearer token string, ready to use directly in an Authorization header.
+
+    .EXAMPLE
+        PS C:\> $token = Get-FscmOdataToken -EnvironmentId "ContosoEnv" -AsObject
+        PS C:\> Invoke-RestMethod -Uri $uri -Headers @{ Authorization = $token.BearerToken }
+
+        This command acquires an OData access token for the environment "ContosoEnv" and returns a typed object with both Token and BearerToken properties.
+
+    .NOTES
+        Author: Mötz Jensen (@Splaxi)
+#>
+function Get-FscmOdataToken {
+    [CmdletBinding(DefaultParameterSetName = 'Default')]
+    [OutputType([System.String], ParameterSetName = 'Default')]
+    [OutputType([System.String], ParameterSetName = 'BearerToken')]
+    [OutputType([System.Management.Automation.PSObject], ParameterSetName = 'Object')]
+    param (
+        [Parameter (Mandatory = $true, ParameterSetName = 'Default')]
+        [Parameter (Mandatory = $true, ParameterSetName = 'BearerToken')]
+        [Parameter (Mandatory = $true, ParameterSetName = 'Object')]
+        [string] $EnvironmentId,
+
+        [Parameter (Mandatory = $true, ParameterSetName = 'BearerToken')]
+        [switch] $AsBearerToken,
+
+        [Parameter (Mandatory = $true, ParameterSetName = 'Object')]
+        [switch] $AsObject
+    )
+
+    begin {
+        # Make sure all *BapEnvironment* cmdlets will validate that the environment exists prior running anything.
+        $envObj = Get-BapEnvironment `
+            -EnvironmentId $EnvironmentId | `
+            Select-Object -First 1
+
+        if ($null -eq $envObj) {
+            $messageString = "The supplied EnvironmentId: <c='em'>$EnvironmentId</c> didn't return any matching environment details. Please verify that the EnvironmentId is correct - try running the <c='em'>Get-BapEnvironment</c> cmdlet."
+            Write-PSFMessage -Level Important -Message $messageString
+            Stop-PSFFunction -Message "Stopping because environment was NOT found based on the id." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
+        }
+
+        if (Test-PSFFunctionInterrupt) { return }
+
+        $baseUri = $envObj.FnOEnvUri -replace '.com/', '.com'
+
+        $secureToken = (Get-AzAccessToken -ResourceUrl $baseUri -AsSecureString).Token
+        $tokenValue = ConvertFrom-SecureString -AsPlainText -SecureString $secureToken
+    }
+
+    process {
+        if (Test-PSFFunctionInterrupt) { return }
+
+        # Branch on the switch parameters so PSScriptAnalyzer sees them as used
+        # (parameter sets alone do not count as usage for PSReviewUnusedParameter).
+        if ($AsObject) {
+            [PSCustomObject]@{ Token = $tokenValue } | `
+                Select-PSFObject -TypeName "D365Bap.Tools.FscmOdataToken" `
+                -Property "Token",
+            @{ Name = "BearerToken"; Expression = { "Bearer $($_.Token)" } }
+        }
+        elseif ($AsBearerToken) {
+            "Bearer $tokenValue"
+        }
+        else {
+            $tokenValue
+        }
+    }
+
+    end {
+
+    }
+}

d365bap.tools/functions/Get-PpacSecurityRoleTable.ps1

@@ -2,55 +2,55 @@
 <#
     .SYNOPSIS
         Get the tables assigned to a security role in a given environment.
-
+        
     .DESCRIPTION
         This cmdlet retrieves the tables (entities) that have privileges assigned to a security role in a given Power Platform environment.
-
+        
         For each table it outputs the access level for each of the privilege types: Create, Read, Write, Delete, Append, AppendTo, Assign and Share.
-
+        
         The access levels are displayed with the Power Platform admin center naming: None, User, Business Unit, Parent: Child Business Unit, Organization.
-
+        
         It mimics the "Tables" view of the security role editor in the Power Platform admin center, with the "Show only assigned tables" filter applied.
-
+        
         Use the Get-PpacTable cmdlet to see all tables available in the environment.
-
+        
     .PARAMETER EnvironmentId
         The ID of the environment to retrieve the security role tables from.
-
+        
         Can be either the environment name, the environment GUID (PPAC) or the LCS environment ID.
-
+        
     .PARAMETER Role
         The security role that you want to work against.
-
+        
         Can be either the role name or the role ID.
-
+        
     .PARAMETER Name
         The name of the table to filter the tables by.
-
+        
         Can be either the table display name or the logical name.
-
+        
         Supports wildcard characters for flexible matching.
-
+        
     .PARAMETER AsExcelOutput
         Instructs the cmdlet to export the retrieved table information to an Excel file.
-
+        
     .EXAMPLE
         PS C:\> Get-PpacSecurityRoleTable -EnvironmentId "ContosoEnv" -Role "Monitoring Reader"
-
+        
         This command retrieves the tables that have privileges assigned to the security role "Monitoring Reader" in the environment "ContosoEnv".
         It will show the access level for each privilege type on each table.
-
+        
     .EXAMPLE
         PS C:\> Get-PpacSecurityRoleTable -EnvironmentId "ContosoEnv" -Role "Monitoring Reader" -Name "*business*"
-
+        
         This command retrieves the tables with display names or logical names matching "*business*", that have privileges assigned to the security role "Monitoring Reader" in the environment "ContosoEnv".
-
+        
     .EXAMPLE
         PS C:\> Get-PpacSecurityRoleTable -EnvironmentId "ContosoEnv" -Role "Monitoring Reader" -AsExcelOutput
-
+        
         This command retrieves the tables that have privileges assigned to the security role "Monitoring Reader" in the environment "ContosoEnv".
         It will export the information to an Excel file.
-
+        
     .NOTES
         Author: Trygve Bechsgaard
 #>
@@ -216,4 +216,4 @@ function Get-PpacSecurityRoleTable {
     end {
 
     }
-}
+}

d365bap.tools/functions/Get-PpacTable.ps1

@@ -2,55 +2,55 @@
 <#
     .SYNOPSIS
         Get the tables (entities) from a given environment.
-
+        
     .DESCRIPTION
         This cmdlet retrieves all tables (entities) from a given Power Platform environment.
-
+        
         It mimics the "Tables" view in the Power Apps maker portal, showing the table display name, logical name, type, managed state and customizability.
-
+        
         It is not specific to any security role - use the Get-PpacSecurityRoleTable cmdlet to see the tables assigned to a security role.
-
+        
     .PARAMETER EnvironmentId
         The ID of the environment to retrieve the tables from.
-
+        
         Can be either the environment name, the environment GUID (PPAC) or the LCS environment ID.
-
+        
     .PARAMETER Name
         The name of the table to filter the tables by.
-
+        
         Can be either the table display name or the logical name.
-
+        
         Supports wildcard characters for flexible matching.
-
+        
     .PARAMETER OnlyCustom
         Instructs the cmdlet to only include custom tables in the results.
-
+        
         This matches the "Custom" filter in the Power Apps maker portal.
-
+        
     .PARAMETER AsExcelOutput
         Instructs the cmdlet to export the retrieved table information to an Excel file.
-
+        
     .EXAMPLE
         PS C:\> Get-PpacTable -EnvironmentId "ContosoEnv"
-
+        
         This command retrieves all tables from the environment "ContosoEnv" and displays their information in the console.
-
+        
     .EXAMPLE
         PS C:\> Get-PpacTable -EnvironmentId "ContosoEnv" -Name "*account*"
-
+        
         This command retrieves all tables with display names or logical names matching "*account*" from the environment "ContosoEnv" and displays their information in the console.
-
+        
     .EXAMPLE
         PS C:\> Get-PpacTable -EnvironmentId "ContosoEnv" -OnlyCustom
-
+        
         This command retrieves only the custom tables from the environment "ContosoEnv" and displays their information in the console.
-
+        
     .EXAMPLE
         PS C:\> Get-PpacTable -EnvironmentId "ContosoEnv" -AsExcelOutput
-
+        
         This command retrieves all tables from the environment "ContosoEnv".
         It will export the information to an Excel file.
-
+        
     .NOTES
         Author: Trygve Bechsgaard
 #>
@@ -151,4 +151,4 @@ function Get-PpacTable {
     end {
 
     }
-}
+}

d365bap.tools/functions/New-PpacSecurityRole.ps1

@@ -2,64 +2,64 @@
 <#
     .SYNOPSIS
         Create a new security role in a given environment.
-
+        
     .DESCRIPTION
         This cmdlet creates a new security role in a given Power Platform environment.
-
+        
         It mimics the "Create New Role" experience of the security role editor in the Power Platform admin center, including the member privilege inheritance option and the option to include the App Opener privileges needed for running Model-Driven apps.
-
+        
         The role is created in the root business unit of the environment, which makes the role available across all business units. Only roles in the root business unit can be modified.
-
+        
         The role is created without any table privileges, unless the App Opener privileges are included.
-
+        
     .PARAMETER EnvironmentId
         The ID of the environment to create the security role in.
-
+        
         Can be either the environment name, the environment GUID (PPAC) or the LCS environment ID.
-
+        
     .PARAMETER Name
         The name of the security role that you want to create.
-
+        
     .PARAMETER Description
         The description of the security role.
-
+        
     .PARAMETER AppliesTo
         The description of the type of users the security role applies to.
-
+        
     .PARAMETER SummaryOfCoreTablePrivileges
         The summary of the core table privileges of the security role.
-
+        
         It is saved in the "summaryofcoretablepermissions" column of the security role.
-
+        
     .PARAMETER MemberPrivilegeInheritance
         The member privilege inheritance that is used when the security role is assigned to a team.
-
+        
         Valid options:
         "DirectUserAndTeamPrivileges" - Team members can inherit team privileges directly, based on the Direct User (Basic) access level.
         "TeamPrivilegesOnly" - Team members get all team privileges by default.
-
+        
         The default value is "DirectUserAndTeamPrivileges".
-
+        
     .PARAMETER IncludeAppOpenerPrivileges
         Instructs the cmdlet to include the App Opener privileges for running Model-Driven apps.
-
+        
         The privileges are copied from the built-in "App Opener" security role in the environment.
-
+        
     .EXAMPLE
         PS C:\> New-PpacSecurityRole -EnvironmentId "ContosoEnv" -Name "Monitoring Reader" -Description "Read access for monitoring" -AppliesTo "Monitoring users" -SummaryOfCoreTablePrivileges "Read access to monitoring tables"
-
+        
         This command creates the security role "Monitoring Reader" in the environment "ContosoEnv".
         The role is created in the root business unit of the environment.
         The role is documented with a description, the type of users it applies to and a summary of its core table privileges.
         The role is created without any table privileges.
-
+        
     .EXAMPLE
         PS C:\> New-PpacSecurityRole -EnvironmentId "ContosoEnv" -Name "Monitoring Reader" -Description "Read access for monitoring" -AppliesTo "Monitoring users" -SummaryOfCoreTablePrivileges "Read access to monitoring tables" -MemberPrivilegeInheritance "TeamPrivilegesOnly" -IncludeAppOpenerPrivileges
-
+        
         This command creates the security role "Monitoring Reader" in the environment "ContosoEnv".
         Team members will get all team privileges by default, when the role is assigned to a team.
         It will include the App Opener privileges for running Model-Driven apps, copied from the built-in "App Opener" security role.
-
+        
     .NOTES
         Author: Trygve Bechsgaard
 #>
@@ -213,4 +213,4 @@ function New-PpacSecurityRole {
     end {
 
     }
-}
+}