Merge pull request #127 from CriticalSolutionsNetwork/Add-Microsoft-Graph-Consent-for-user-function
Add microsoft graph consent for user function
This commit is contained in:
Doug Rios
GitHub
@@ -4,6 +4,12 @@ The format is based on and uses the types of changes according to [Keep a Change
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
|
||||
- Added `Grant-M365SecurityAuditConsent` function to consent to the Microsoft Graph Powershell API for a user.
|
||||
|
||||
## [0.1.15] - 2024-06-26
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fixed test 8.6.1 to include all of the following properties in it's checks and output: `ReportJunkToCustomizedAddress`, `ReportNotJunkToCustomizedAddress`, `ReportPhishToCustomizedAddress`,`ReportJunkAddresses`,`ReportNotJunkAddresses`,`ReportPhishAddresses`,`ReportChatMessageEnabled`,`ReportChatMessageToCustomizedAddressEnabled`
|
||||
|
||||
BIN
docs/index.html
BIN
docs/index.html
Binary file not shown.
@@ -1,4 +1,4 @@
|
||||
---
|
||||
---
|
||||
external help file: M365FoundationsCISReport-help.xml
|
||||
Module Name: M365FoundationsCISReport
|
||||
online version: https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Export-M365SecurityAuditTable
|
||||
@@ -110,22 +110,6 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -OutputTestNumber
|
||||
The test number to output as an object.
|
||||
Valid values are "1.1.1", "1.3.1", "6.1.2", "6.1.3", "7.3.4".
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Parameter Sets: OutputObjectFromAuditResultsSingle, OutputObjectFromCsvSingle
|
||||
Aliases:
|
||||
|
||||
Required: True
|
||||
Position: 2
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ExportAllTests
|
||||
Switch to export all test results.
|
||||
|
||||
@@ -141,6 +125,21 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ExportOriginalTests
|
||||
Switch to export the original audit results to a CSV file.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: ExportAllResultsFromAuditResults, ExportAllResultsFromCsv
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: False
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ExportPath
|
||||
The path where the CSV files will be exported.
|
||||
|
||||
@@ -156,8 +155,8 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ExportOriginalTests
|
||||
Switch to export the original audit results to a CSV file.
|
||||
### -ExportToExcel
|
||||
Switch to export the results to an Excel file.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
@@ -171,17 +170,18 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ExportToExcel
|
||||
Switch to export the results to an Excel file.
|
||||
### -OutputTestNumber
|
||||
The test number to output as an object.
|
||||
Valid values are "1.1.1", "1.3.1", "6.1.2", "6.1.3", "7.3.4".
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: ExportAllResultsFromAuditResults, ExportAllResultsFromCsv
|
||||
Type: String
|
||||
Parameter Sets: OutputObjectFromAuditResultsSingle, OutputObjectFromCsvSingle
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: False
|
||||
Required: True
|
||||
Position: 2
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
---
|
||||
---
|
||||
external help file: M365FoundationsCISReport-help.xml
|
||||
Module Name: M365FoundationsCISReport
|
||||
online version: https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Get-AdminRoleUserLicense
|
||||
@@ -38,6 +38,21 @@ This example retrieves all administrative role users along with their licenses w
|
||||
|
||||
## PARAMETERS
|
||||
|
||||
### -ProgressAction
|
||||
{{ Fill ProgressAction Description }}
|
||||
|
||||
```yaml
|
||||
Type: ActionPreference
|
||||
Parameter Sets: (All)
|
||||
Aliases: proga
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -SkipGraphConnection
|
||||
A switch parameter that, when set, skips the connection to Microsoft Graph if already established.
|
||||
This is useful for batch processing or when used within scripts where multiple calls are made and the connection is managed externally.
|
||||
@@ -54,21 +69,6 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ProgressAction
|
||||
{{ Fill ProgressAction Description }}
|
||||
|
||||
```yaml
|
||||
Type: ActionPreference
|
||||
Parameter Sets: (All)
|
||||
Aliases: proga
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### CommonParameters
|
||||
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
---
|
||||
---
|
||||
external help file: M365FoundationsCISReport-help.xml
|
||||
Module Name: M365FoundationsCISReport
|
||||
online version: https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Get-MFAStatus
|
||||
@@ -37,17 +37,16 @@ Retrieves the MFA status for the specified user with the UPN "example@domain.com
|
||||
|
||||
## PARAMETERS
|
||||
|
||||
### -UserId
|
||||
The User Principal Name (UPN) of a specific user to retrieve MFA status for.
|
||||
If not provided, the function retrieves MFA status for all users.
|
||||
### -ProgressAction
|
||||
{{ Fill ProgressAction Description }}
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Type: ActionPreference
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
Aliases: proga
|
||||
|
||||
Required: False
|
||||
Position: 1
|
||||
Position: Named
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
@@ -68,16 +67,17 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ProgressAction
|
||||
{{ Fill ProgressAction Description }}
|
||||
### -UserId
|
||||
The User Principal Name (UPN) of a specific user to retrieve MFA status for.
|
||||
If not provided, the function retrieves MFA status for all users.
|
||||
|
||||
```yaml
|
||||
Type: ActionPreference
|
||||
Type: String
|
||||
Parameter Sets: (All)
|
||||
Aliases: proga
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Position: 1
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
|
||||
179
help/Grant-M365SecurityAuditConsent.md
Normal file
179
help/Grant-M365SecurityAuditConsent.md
Normal file
@@ -0,0 +1,179 @@
|
||||
---
|
||||
external help file: M365FoundationsCISReport-help.xml
|
||||
Module Name: M365FoundationsCISReport
|
||||
online version: https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Grant-M365SecurityAuditConsent
|
||||
schema: 2.0.0
|
||||
---
|
||||
|
||||
# Grant-M365SecurityAuditConsent
|
||||
|
||||
## SYNOPSIS
|
||||
Grants Microsoft Graph permissions for an auditor.
|
||||
|
||||
## SYNTAX
|
||||
|
||||
```
|
||||
Grant-M365SecurityAuditConsent [-UserPrincipalNameForConsent] <String> [-SkipGraphConnection]
|
||||
[-SkipModuleCheck] [-SuppressRevertOutput] [-DoNotDisconnect] [-ProgressAction <ActionPreference>] [-WhatIf]
|
||||
[-Confirm] [<CommonParameters>]
|
||||
```
|
||||
|
||||
## DESCRIPTION
|
||||
This function grants the specified Microsoft Graph permissions to a user, allowing the user to perform audits.
|
||||
It connects to Microsoft Graph, checks if a service principal exists for the client application, creates it if it does not exist, and then grants the specified permissions.
|
||||
Finally, it assigns the app to the user.
|
||||
|
||||
## EXAMPLES
|
||||
|
||||
### EXAMPLE 1
|
||||
```
|
||||
Grant-M365SecurityAuditConsent -UserPrincipalNameForConsent user@example.com
|
||||
```
|
||||
|
||||
Grants Microsoft Graph permissions to user@example.com for the client application with the specified Application ID.
|
||||
|
||||
### EXAMPLE 2
|
||||
```
|
||||
Grant-M365SecurityAuditConsent -UserPrincipalNameForConsent user@example.com -SkipGraphConnection
|
||||
```
|
||||
|
||||
Grants Microsoft Graph permissions to user@example.com, skipping the connection to Microsoft Graph.
|
||||
|
||||
## PARAMETERS
|
||||
|
||||
### -DoNotDisconnect
|
||||
If specified, does not disconnect from Microsoft Graph after granting consent.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: False
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ProgressAction
|
||||
{{ Fill ProgressAction Description }}
|
||||
|
||||
```yaml
|
||||
Type: ActionPreference
|
||||
Parameter Sets: (All)
|
||||
Aliases: proga
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -SkipGraphConnection
|
||||
If specified, skips connecting to Microsoft Graph.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: False
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -SkipModuleCheck
|
||||
If specified, skips the check for the Microsoft.Graph module.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: False
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -SuppressRevertOutput
|
||||
If specified, suppresses the output of the revert commands.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: False
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -UserPrincipalNameForConsent
|
||||
Specify the UPN of the user to grant consent for.
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: True
|
||||
Position: 1
|
||||
Default value: None
|
||||
Accept pipeline input: True (ByPropertyName, ByValue)
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -Confirm
|
||||
Prompts you for confirmation before running the cmdlet.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases: cf
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -WhatIf
|
||||
Shows what would happen if the cmdlet runs.
|
||||
The cmdlet is not run.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases: wi
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### CommonParameters
|
||||
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
|
||||
|
||||
## INPUTS
|
||||
|
||||
## OUTPUTS
|
||||
|
||||
### System.Void
|
||||
## NOTES
|
||||
This function requires the Microsoft.Graph module version 2.4.0 or higher.
|
||||
|
||||
## RELATED LINKS
|
||||
|
||||
[https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Grant-M365SecurityAuditConsent](https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Grant-M365SecurityAuditConsent)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
---
|
||||
---
|
||||
external help file: M365FoundationsCISReport-help.xml
|
||||
Module Name: M365FoundationsCISReport
|
||||
online version: https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Invoke-M365SecurityAudit
|
||||
@@ -164,34 +164,47 @@ What if: Performing the operation "Invoke-M365SecurityAudit" on target "Microsof
|
||||
|
||||
## PARAMETERS
|
||||
|
||||
### -TenantAdminUrl
|
||||
The URL of the tenant admin.
|
||||
If not specified, none of the SharePoint Online tests will run.
|
||||
### -DoNotConfirmConnections
|
||||
If specified, the cmdlet will not prompt for confirmation before proceeding with established connections and will disconnect from all of them.
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: None
|
||||
Default value: False
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -M365DomainForPWPolicyTest
|
||||
The domain name of the Microsoft 365 environment to test.
|
||||
This parameter is not mandatory and by default it will pass/fail all found domains as a group if a specific domain is not specified.
|
||||
### -DoNotConnect
|
||||
If specified, the cmdlet will not establish a connection to Microsoft 365 services.
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: None
|
||||
Default value: False
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -DoNotDisconnect
|
||||
If specified, the cmdlet will not disconnect from Microsoft 365 services after execution.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: False
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
@@ -212,22 +225,6 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ProfileLevel
|
||||
Specifies the profile level (L1 or L2) for the audit.
|
||||
This parameter is optional and can be combined with the ELevel parameter.
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Parameter Sets: ELevelFilter
|
||||
Aliases:
|
||||
|
||||
Required: True
|
||||
Position: Named
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -IncludeIG1
|
||||
If specified, includes tests where IG1 is true.
|
||||
|
||||
@@ -289,52 +286,22 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -SkipRecommendation
|
||||
Specifies specific recommendations to exclude from the audit.
|
||||
Accepts an array of recommendation numbers.
|
||||
### -M365DomainForPWPolicyTest
|
||||
The domain name of the Microsoft 365 environment to test.
|
||||
This parameter is not mandatory and by default it will pass/fail all found domains as a group if a specific domain is not specified.
|
||||
|
||||
```yaml
|
||||
Type: String[]
|
||||
Parameter Sets: SkipRecFilter
|
||||
Type: String
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: True
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -DoNotConnect
|
||||
If specified, the cmdlet will not establish a connection to Microsoft 365 services.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: False
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -DoNotDisconnect
|
||||
If specified, the cmdlet will not disconnect from Microsoft 365 services after execution.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: False
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -NoModuleCheck
|
||||
If specified, the cmdlet will not check for the presence of required modules.
|
||||
|
||||
@@ -350,29 +317,61 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -DoNotConfirmConnections
|
||||
If specified, the cmdlet will not prompt for confirmation before proceeding with established connections and will disconnect from all of them.
|
||||
### -ProfileLevel
|
||||
Specifies the profile level (L1 or L2) for the audit.
|
||||
This parameter is optional and can be combined with the ELevel parameter.
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Type: String
|
||||
Parameter Sets: ELevelFilter
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Required: True
|
||||
Position: Named
|
||||
Default value: False
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -WhatIf
|
||||
Shows what would happen if the cmdlet runs.
|
||||
The cmdlet is not run.
|
||||
### -ProgressAction
|
||||
{{ Fill ProgressAction Description }}
|
||||
|
||||
```yaml
|
||||
Type: SwitchParameter
|
||||
Type: ActionPreference
|
||||
Parameter Sets: (All)
|
||||
Aliases: wi
|
||||
Aliases: proga
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -SkipRecommendation
|
||||
Specifies specific recommendations to exclude from the audit.
|
||||
Accepts an array of recommendation numbers.
|
||||
|
||||
```yaml
|
||||
Type: String[]
|
||||
Parameter Sets: SkipRecFilter
|
||||
Aliases:
|
||||
|
||||
Required: True
|
||||
Position: Named
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -TenantAdminUrl
|
||||
The URL of the tenant admin.
|
||||
If not specified, none of the SharePoint Online tests will run.
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
@@ -396,13 +395,14 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ProgressAction
|
||||
{{ Fill ProgressAction Description }}
|
||||
### -WhatIf
|
||||
Shows what would happen if the cmdlet runs.
|
||||
The cmdlet is not run.
|
||||
|
||||
```yaml
|
||||
Type: ActionPreference
|
||||
Type: SwitchParameter
|
||||
Parameter Sets: (All)
|
||||
Aliases: proga
|
||||
Aliases: wi
|
||||
|
||||
Required: False
|
||||
Position: Named
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
---
|
||||
---
|
||||
external help file: M365FoundationsCISReport-help.xml
|
||||
Module Name: M365FoundationsCISReport
|
||||
online version:
|
||||
@@ -46,21 +46,6 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -WorksheetName
|
||||
The name of the worksheet within the Excel file to be processed.
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: True
|
||||
Position: 2
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -ProgressAction
|
||||
{{ Fill ProgressAction Description }}
|
||||
|
||||
@@ -76,6 +61,21 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -WorksheetName
|
||||
The name of the worksheet within the Excel file to be processed.
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: True
|
||||
Position: 2
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### CommonParameters
|
||||
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
---
|
||||
---
|
||||
external help file: M365FoundationsCISReport-help.xml
|
||||
Module Name: M365FoundationsCISReport
|
||||
online version: https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Sync-CISExcelAndCsvData
|
||||
@@ -32,22 +32,6 @@ Updates the 'AuditData' worksheet in 'excel.xlsx' with data from 'data.csv', add
|
||||
|
||||
## PARAMETERS
|
||||
|
||||
### -ExcelPath
|
||||
Specifies the path to the Excel file to be updated.
|
||||
This parameter is mandatory.
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: 1
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -CsvPath
|
||||
Specifies the path to the CSV file containing new data.
|
||||
This parameter is mandatory.
|
||||
@@ -64,8 +48,8 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -SheetName
|
||||
Specifies the name of the worksheet in the Excel file where data will be merged and updated.
|
||||
### -ExcelPath
|
||||
Specifies the path to the Excel file to be updated.
|
||||
This parameter is mandatory.
|
||||
|
||||
```yaml
|
||||
@@ -74,7 +58,7 @@ Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: 3
|
||||
Position: 1
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
@@ -95,6 +79,22 @@ Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### -SheetName
|
||||
Specifies the name of the worksheet in the Excel file where data will be merged and updated.
|
||||
This parameter is mandatory.
|
||||
|
||||
```yaml
|
||||
Type: String
|
||||
Parameter Sets: (All)
|
||||
Aliases:
|
||||
|
||||
Required: False
|
||||
Position: 3
|
||||
Default value: None
|
||||
Accept pipeline input: False
|
||||
Accept wildcard characters: False
|
||||
```
|
||||
|
||||
### CommonParameters
|
||||
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
|
||||
|
||||
|
||||
@@ -33,6 +33,9 @@ Remove-RowsWithEmptyCSVStatus -FilePath "C:\Reports\Report.xlsx" -WorksheetName
|
||||
|
||||
# Example 6: Synchronizing CIS benchmark data with audit results
|
||||
Sync-CISExcelAndCsvData -ExcelPath "path\to\excel.xlsx" -CsvPath "path\to\data.csv" -SheetName "Combined Profiles"
|
||||
|
||||
# Example 7: Granting Microsoft Graph permissions to the auditor
|
||||
Grant-M365SecurityAuditConsent -UserPrincipalNameForConsent 'user@example.com'
|
||||
```
|
||||
|
||||
# NOTE
|
||||
|
||||
@@ -4,7 +4,7 @@ Import-Module .\output\module\M365FoundationsCISReport\*\*.psd1
|
||||
|
||||
|
||||
<#
|
||||
$ver = "v0.1.14"
|
||||
$ver = "v0.1.15"
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git tag -a $ver -m "Release version $ver refactor Update"
|
||||
@@ -39,4 +39,26 @@ $parameters = @{
|
||||
}
|
||||
Update-MarkdownHelpModule @parameters -Force
|
||||
Update-MarkdownHelpModule -Path ".\help" -RefreshModulePage -Force
|
||||
New-ExternalHelp -Path ".\help" -OutputPath ".\source\en-US" -force
|
||||
New-ExternalHelp -Path ".\help" -OutputPath ".\source\en-US" -force
|
||||
|
||||
|
||||
|
||||
# Install Secret Management
|
||||
Install-Module -Name "Microsoft.PowerShell.SecretManagement", `
|
||||
"SecretManagement.JustinGrote.CredMan" -Scope CurrentUser
|
||||
|
||||
# Register Vault
|
||||
Register-SecretVault -Name ModuleBuildCreds -ModuleName `
|
||||
"SecretManagement.JustinGrote.CredMan" -ErrorAction Stop
|
||||
|
||||
|
||||
Set-Secret -Name "GalleryApiToken" -Vault ModuleBuildCreds
|
||||
Set-Secret -Name "GitHubToken" -Vault ModuleBuildCreds
|
||||
|
||||
|
||||
$GalleryApiToken = Get-Secret -Name "GalleryApiToken" -Vault ModuleBuildCreds -AsPlainText
|
||||
$GitHubToken = Get-Secret -Name "GitHubToken" -Vault ModuleBuildCreds -AsPlainText
|
||||
|
||||
|
||||
$GalleryApiToken
|
||||
$GitHubToken
|
||||
|
||||
182
source/Public/Grant-M365SecurityAuditConsent.ps1
Normal file
182
source/Public/Grant-M365SecurityAuditConsent.ps1
Normal file
@@ -0,0 +1,182 @@
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Grants Microsoft Graph permissions for an auditor.
|
||||
.DESCRIPTION
|
||||
This function grants the specified Microsoft Graph permissions to a user, allowing the user to perform audits. It connects to Microsoft Graph, checks if a service principal exists for the client application, creates it if it does not exist, and then grants the specified permissions. Finally, it assigns the app to the user.
|
||||
.PARAMETER UserPrincipalNameForConsent
|
||||
The UPN or ID of the user to grant consent for.
|
||||
.PARAMETER SkipGraphConnection
|
||||
If specified, skips connecting to Microsoft Graph.
|
||||
.PARAMETER DoNotDisconnect
|
||||
If specified, does not disconnect from Microsoft Graph after granting consent.
|
||||
.PARAMETER SkipModuleCheck
|
||||
If specified, skips the check for the Microsoft.Graph module.
|
||||
.PARAMETER SuppressRevertOutput
|
||||
If specified, suppresses the output of the revert commands.
|
||||
.EXAMPLE
|
||||
Grant-M365SecurityAuditConsent -UserPrincipalNameForConsent user@example.com
|
||||
|
||||
Grants Microsoft Graph permissions to user@example.com for the client application with the specified Application ID.
|
||||
.EXAMPLE
|
||||
Grant-M365SecurityAuditConsent -UserPrincipalNameForConsent user@example.com -SkipGraphConnection
|
||||
|
||||
Grants Microsoft Graph permissions to user@example.com, skipping the connection to Microsoft Graph.
|
||||
.NOTES
|
||||
This function requires the Microsoft.Graph module version 2.4.0 or higher.
|
||||
.LINK
|
||||
https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Grant-M365SecurityAuditConsent
|
||||
#>
|
||||
function Grant-M365SecurityAuditConsent {
|
||||
[CmdletBinding(
|
||||
SupportsShouldProcess = $true,
|
||||
ConfirmImpact = 'High'
|
||||
)]
|
||||
[OutputType([void])]
|
||||
param (
|
||||
[Parameter(
|
||||
Mandatory = $true,
|
||||
Position = 0,
|
||||
ValueFromPipeline = $true,
|
||||
ValueFromPipelineByPropertyName = $true,
|
||||
HelpMessage = 'Specify the UPN of the user to grant consent for.'
|
||||
)]
|
||||
[ValidatePattern('^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$')]
|
||||
[String]$UserPrincipalNameForConsent,
|
||||
[Parameter(
|
||||
Mandatory = $false,
|
||||
HelpMessage = 'Skip connecting to Microsoft Graph.'
|
||||
)]
|
||||
[switch]$SkipGraphConnection,
|
||||
[Parameter(
|
||||
Mandatory = $false,
|
||||
HelpMessage = 'Skip the check for the Microsoft.Graph module.'
|
||||
)]
|
||||
[switch]$SkipModuleCheck,
|
||||
[Parameter(
|
||||
Mandatory = $false,
|
||||
HelpMessage = 'Suppress the output of the revert commands.'
|
||||
)]
|
||||
[switch]$SuppressRevertOutput,
|
||||
[Parameter(
|
||||
Mandatory = $false,
|
||||
HelpMessage = 'Do not disconnect from Microsoft Graph after granting consent.'
|
||||
)]
|
||||
[switch]$DoNotDisconnect
|
||||
)
|
||||
begin {
|
||||
if (!($SkipModuleCheck)) {
|
||||
Assert-ModuleAvailability -ModuleName Microsoft.Graph -RequiredVersion "2.4.0"
|
||||
}
|
||||
# Adjusted from: https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-consent-single-user?pivots=msgraph-powershell
|
||||
# Needed: A user account with a Privileged Role Administrator, Application Administrator, or Cloud Application Administrator
|
||||
# The app for which consent is being granted.
|
||||
$clientAppId = "14d82eec-204b-4c2f-b7e8-296a70dab67e" # Microsoft Graph PowerShell
|
||||
# The API to which access will be granted. Microsoft Graph PowerShell makes API
|
||||
# requests to the Microsoft Graph API, so we'll use that here.
|
||||
$resourceAppId = "00000003-0000-0000-c000-000000000000" # Microsoft Graph API
|
||||
# The permissions to grant.
|
||||
$permissions = @("Directory.Read.All", "Domain.Read.All", "Policy.Read.All", "Organization.Read.All")
|
||||
# The user on behalf of whom access will be granted. The app will be able to access
|
||||
# the API on behalf of this user.
|
||||
$userUpnOrId = $UserPrincipalNameForConsent
|
||||
}
|
||||
process {
|
||||
try {
|
||||
if (-not $SkipGraphConnection -and $PSCmdlet.ShouldProcess("Scopes: User.ReadBasic.All, Application.ReadWrite.All, DelegatedPermissionGrant.ReadWrite.All, AppRoleAssignment.ReadWrite.All", "Connect-MgGraph")) {
|
||||
# Step 0. Connect to Microsoft Graph PowerShell. We need User.ReadBasic.All to get
|
||||
# users' IDs, Application.ReadWrite.All to list and create service principals,
|
||||
# DelegatedPermissionGrant.ReadWrite.All to create delegated permission grants,
|
||||
# and AppRoleAssignment.ReadWrite.All to assign an app role.
|
||||
# WARNING: These are high-privilege permissions!
|
||||
Write-Host "Connecting to Microsoft Graph with scopes: User.ReadBasic.All, Application.ReadWrite.All, DelegatedPermissionGrant.ReadWrite.All, AppRoleAssignment.ReadWrite.All" -ForegroundColor Yellow
|
||||
Connect-MgGraph -Scopes ("User.ReadBasic.All Application.ReadWrite.All " + "DelegatedPermissionGrant.ReadWrite.All " + "AppRoleAssignment.ReadWrite.All") -NoWelcome
|
||||
$context = Get-MgContext
|
||||
Write-Host "Connected to Microsoft Graph with user: $(($context.Account)) with the authtype `"$($context.AuthType)`" for the `"$($context.Environment)`" environment." -ForegroundColor Green
|
||||
}
|
||||
}
|
||||
catch {
|
||||
throw "Connection execution aborted: $_"
|
||||
break
|
||||
}
|
||||
try {
|
||||
if ($PSCmdlet.ShouldProcess("Create Microsoft Graph API service princial if not found", "New-MgServicePrincipal")) {
|
||||
# Step 1. Check if a service principal exists for the client application.
|
||||
# If one doesn't exist, create it.
|
||||
$clientSp = Get-MgServicePrincipal -Filter "appId eq '$($clientAppId)'" -ErrorAction SilentlyContinue
|
||||
if (-not $clientSp) {
|
||||
Write-Host "Client service principal not found. Creating one." -ForegroundColor Yellow
|
||||
$clientSp = New-MgServicePrincipal -AppId $clientAppId
|
||||
}
|
||||
$user = Get-MgUser -UserId $userUpnOrId
|
||||
if (!($user)) {
|
||||
throw "User with UPN or ID `"$userUpnOrId`" not found."
|
||||
}
|
||||
Write-Verbose "User: $($user.UserPrincipalName) Found!"
|
||||
$resourceSp = Get-MgServicePrincipal -Filter "appId eq '$($resourceAppId)'"
|
||||
$scopeToGrant = $permissions -join " "
|
||||
$existingGrant = Get-MgOauth2PermissionGrant -Filter "clientId eq '$($clientSp.Id)' and principalId eq '$($user.Id)' and resourceId eq '$($resourceSp.Id)'"
|
||||
}
|
||||
if (-not $existingGrant -and $PSCmdlet.ShouldProcess("User: $userUpnOrId for Microsoft Graph PowerShell Scopes: $($permissions -join ', ')", "New-MgOauth2PermissionGrant: Granting Consent")) {
|
||||
# Step 2. Create a delegated permission that grants the client app access to the
|
||||
# API, on behalf of the user.
|
||||
$grant = New-MgOauth2PermissionGrant -ResourceId $resourceSp.Id -Scope $scopeToGrant -ClientId $clientSp.Id -ConsentType "Principal" -PrincipalId $user.Id
|
||||
Write-Host "Consent granted to user $($user.UserPrincipalName) for Microsoft Graph API with scopes: $((($grant.Scope) -split ' ') -join ', ')" -ForegroundColor Green
|
||||
}
|
||||
if ($existingGrant -and $PSCmdlet.ShouldProcess("Update existing Microsoft Graph permissions for user $userUpnOrId", "Update-MgOauth2PermissionGrant")) {
|
||||
# Step 2. Update the existing permission grant with the new scopes.
|
||||
Write-Host "Updating existing permission grant for user $($user.UserPrincipalName)." -ForegroundColor Yellow
|
||||
$updatedGrant = Update-MgOauth2PermissionGrant -PermissionGrantId $existingGrant.Id -Scope $scopeToGrant -Confirm:$false
|
||||
Write-Host "Updated permission grant with ID $($updatedGrant.Id) for scopes: $scopeToGrant" -ForegroundColor Green
|
||||
}
|
||||
if ($PSCmdlet.ShouldProcess("Assigning app to user $userUpnOrId", "New-MgServicePrincipalAppRoleAssignedTo")) {
|
||||
# Step 3. Assign the app to the user. This ensures that the user can sign in if assignment
|
||||
# is required, and ensures that the app shows up under the user's My Apps portal.
|
||||
if ($clientSp.AppRoles | Where-Object { $_.AllowedMemberTypes -contains "User" }) {
|
||||
Write-Warning "A default app role assignment cannot be created because the client application exposes user-assignable app roles. You must assign the user a specific app role for the app to be listed in the user's My Apps access panel."
|
||||
}
|
||||
else {
|
||||
# The app role ID 00000000-0000-0000-0000-000000000000 is the default app role
|
||||
# indicating that the app is assigned to the user, but not for any specific
|
||||
# app role.
|
||||
$assignment = New-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $clientSp.Id -ResourceId $clientSp.Id -PrincipalId $user.Id -AppRoleId "00000000-0000-0000-0000-000000000000"
|
||||
# $assignments = Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $assignment.ResourceId -All -WhatIf
|
||||
}
|
||||
}
|
||||
}
|
||||
catch {
|
||||
throw "An error occurred while granting consent:`n$_"
|
||||
}
|
||||
finally {
|
||||
if (!($DoNotDisconnect) -and $PSCmdlet.ShouldProcess("Disconnect from Microsoft Graph", "Disconnect")) {
|
||||
# Clean up sessions
|
||||
Write-Host "Disconnecting from Microsoft Graph." -ForegroundColor Yellow
|
||||
Disconnect-MgGraph | Out-Null
|
||||
}
|
||||
}
|
||||
}
|
||||
end {
|
||||
if (-not $SuppressRevertOutput -and $PSCmdlet.ShouldProcess("Instructions to undo this change", "Generate Revert Commands")) {
|
||||
<#
|
||||
# Instructions to revert the changes made by this script
|
||||
$resourceAppId = "00000003-0000-0000-c000-000000000000"
|
||||
$clientAppId = "14d82eec-204b-4c2f-b7e8-296a70dab67e"
|
||||
# Get the user object
|
||||
#$user = Get-MgUser -UserId "user@example.com"
|
||||
$resourceSp = Get-MgServicePrincipal -Filter "appId eq '$($resourceAppId)'"
|
||||
# Get the service principal using $clientAppId
|
||||
$clientSp = Get-MgServicePrincipal -Filter "appId eq '$($clientAppId)'"
|
||||
$existingGrant = Get-MgOauth2PermissionGrant -Filter "clientId eq '$($clientSp.Id)' and principalId eq '$($user.Id)' and resourceId eq '$($resourceSp.Id)'"
|
||||
# Get all app role assignments for the service principal
|
||||
$appRoleAssignments = Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $clientSp.Id -All
|
||||
# At index of desired user assignment
|
||||
Remove-MgServicePrincipalAppRoleAssignedTo -AppRoleAssignmentId $appRoleAssignments[1].Id -ServicePrincipalId $clientSp.Id
|
||||
Remove-MgOAuth2PermissionGrant -OAuth2PermissionGrantId $existingGrant.Id
|
||||
#>
|
||||
Write-Host "App assigned to user $($assignment.PrincipalDisplayName) for $($assignment.ResourceDisplayName) at $($assignment.CreatedDateTime)." -ForegroundColor Green
|
||||
Write-Host "If you made a mistake and would like to remove the assignement for `"$($user.UserPrincipalName)`", you can run the following:`n" -ForegroundColor Yellow
|
||||
Write-Host "Connect-MgGraph -Scopes (`"User.ReadBasic.All Application.ReadWrite.All `" + `"DelegatedPermissionGrant.ReadWrite.All `" + `"AppRoleAssignment.ReadWrite.All`")" -ForegroundColor Cyan
|
||||
Write-Host "Remove-MgServicePrincipalAppRoleAssignedTo -AppRoleAssignmentId `"$($assignment.Id)`" -ServicePrincipalId `"$($assignment.ResourceId)`"" -ForegroundColor Cyan
|
||||
Write-Host "Remove-MgOAuth2PermissionGrant -OAuth2PermissionGrantId `"$($grant.Id)`"" -ForegroundColor Cyan
|
||||
}
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -45,6 +45,9 @@ EXAMPLES
|
||||
|
||||
# Example 6: Synchronizing CIS benchmark data with audit results
|
||||
Sync-CISExcelAndCsvData -ExcelPath "path\to\excel.xlsx" -CsvPath "path\to\data.csv" -SheetName "Combined Profiles"
|
||||
|
||||
# Example 7: Granting Microsoft Graph permissions to the auditor
|
||||
Grant-M365SecurityAuditConsent -UserPrincipalNameForConsent 'user@example.com'
|
||||
|
||||
NOTE
|
||||
Ensure that you have the necessary permissions and administrative roles in
|
||||
|
||||
71
tests/Unit/Public/Grant-M365SecurityAuditConsent.tests.ps1
Normal file
71
tests/Unit/Public/Grant-M365SecurityAuditConsent.tests.ps1
Normal file
@@ -0,0 +1,71 @@
|
||||
BeforeAll {
|
||||
$script:moduleName = '<% $PLASTER_PARAM_ModuleName %>'
|
||||
|
||||
# If the module is not found, run the build task 'noop'.
|
||||
if (-not (Get-Module -Name $script:moduleName -ListAvailable))
|
||||
{
|
||||
# Redirect all streams to $null, except the error stream (stream 2)
|
||||
& "$PSScriptRoot/../../build.ps1" -Tasks 'noop' 2>&1 4>&1 5>&1 6>&1 > $null
|
||||
}
|
||||
|
||||
# Re-import the module using force to get any code changes between runs.
|
||||
Import-Module -Name $script:moduleName -Force -ErrorAction 'Stop'
|
||||
|
||||
$PSDefaultParameterValues['InModuleScope:ModuleName'] = $script:moduleName
|
||||
$PSDefaultParameterValues['Mock:ModuleName'] = $script:moduleName
|
||||
$PSDefaultParameterValues['Should:ModuleName'] = $script:moduleName
|
||||
}
|
||||
|
||||
AfterAll {
|
||||
$PSDefaultParameterValues.Remove('Mock:ModuleName')
|
||||
$PSDefaultParameterValues.Remove('InModuleScope:ModuleName')
|
||||
$PSDefaultParameterValues.Remove('Should:ModuleName')
|
||||
|
||||
Remove-Module -Name $script:moduleName
|
||||
}
|
||||
|
||||
Describe Get-Something {
|
||||
|
||||
Context 'Return values' {
|
||||
BeforeEach {
|
||||
$return = Get-Something -Data 'value'
|
||||
}
|
||||
|
||||
It 'Returns a single object' {
|
||||
($return | Measure-Object).Count | Should -Be 1
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
Context 'Pipeline' {
|
||||
It 'Accepts values from the pipeline by value' {
|
||||
$return = 'value1', 'value2' | Get-Something
|
||||
|
||||
$return[0] | Should -Be 'value1'
|
||||
$return[1] | Should -Be 'value2'
|
||||
}
|
||||
|
||||
It 'Accepts value from the pipeline by property name' {
|
||||
$return = 'value1', 'value2' | ForEach-Object {
|
||||
[PSCustomObject]@{
|
||||
Data = $_
|
||||
OtherProperty = 'other'
|
||||
}
|
||||
} | Get-Something
|
||||
|
||||
|
||||
$return[0] | Should -Be 'value1'
|
||||
$return[1] | Should -Be 'value2'
|
||||
}
|
||||
}
|
||||
|
||||
Context 'ShouldProcess' {
|
||||
It 'Supports WhatIf' {
|
||||
(Get-Command Get-Something).Parameters.ContainsKey('WhatIf') | Should -Be $true
|
||||
{ Get-Something -Data 'value' -WhatIf } | Should -Not -Throw
|
||||
}
|
||||
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user