Skip to content

Commit

Permalink
Add functionality to run non interactive
Browse files Browse the repository at this point in the history
  • Loading branch information
ThomasKur committed Jul 21, 2020
1 parent 64cde55 commit cd829bc
Show file tree
Hide file tree
Showing 6 changed files with 246 additions and 13 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ Function Invoke-IntuneDocumentation(){
NOTE: This no longer does Conditional Access
The Script is using the PSWord and Microsoft.Graph.Intune Module. Therefore you have to install them first.
.PARAMETER FullDocumentationPath
Path including filename where the documentation should be created. The filename has to end with .docx.
Note:
Expand All @@ -17,9 +19,23 @@ Function Invoke-IntuneDocumentation(){
to support this project. You can do this by translating the json files which are mentioned to you when
you generate the documentation in your tenant.
.EXAMPLE
.PARAMETER ClientSecret
If the client secret is set, app-only authentication will be performed using the client ID specified by
the AppId environment parameter.
.PARAMETER ClientId
The client id of the application registration with the required permissions.
.PARAMETER Tenant
Name of your tenant in form of "kurcontoso.onmicrosoft.com" or the TenantId
.EXAMPLE Interactive
Invoke-IntuneDocumentation -FullDocumentationPath c:\temp\IntuneDoc.docx
.EXAMPLE Non interactive
Invoke-IntuneDocumentation -FullDocumentationPath c:\temp\IntuneDoc.docx -ClientId d5cf6364-82f7-4024-9ac1-73a9fd2a6ec3 -ClientSecret S03AESdMlhLQIPYYw/cYtLkGkQS0H49jXh02AS6Ek0U= -Tenant d873f16a-73a2-4ccf-9d36-67b8243ab99a
.NOTES
Author: Thomas Kurth/baseVISION
Co-Author: jflieben
Expand All @@ -29,10 +45,6 @@ Function Invoke-IntuneDocumentation(){
History
See Release Notes in Github.
ExitCodes:
99001: Could not Write to LogFile
99002: Could not Write to Windows Log
99003: Could not Set ExitMessageRegistry
#>
[CmdletBinding()]
Param(
Expand All @@ -42,8 +54,22 @@ Function Invoke-IntuneDocumentation(){
}
return $true
})]
[Parameter(ParameterSetName = "NonInteractive")]
[Parameter(ParameterSetName = "Default")]
[System.IO.FileInfo]$FullDocumentationPath = ".\IntuneDocumentation.docx",
[switch]$UseTranslationBeta

[Parameter(ParameterSetName = "Default")]
[Parameter(ParameterSetName = "NonInteractive")]
[switch]$UseTranslationBeta,

[Parameter(Mandatory = $true, ParameterSetName = "NonInteractive")]
[String]$ClientId,

[Parameter(Mandatory = $true, ParameterSetName = "NonInteractive")]
[String]$ClientSecret,

[Parameter(Mandatory = $true, ParameterSetName = "NonInteractive")]
[String]$Tenant

)
## Manual Variable Definition
Expand All @@ -61,7 +87,14 @@ Function Invoke-IntuneDocumentation(){
########################################################
Write-Log "Start Script $Scriptname"
#region Authentication
Connect-MSGraph
if($PsCmdlet.ParameterSetName -eq "NonInteractive"){
$authority = "https://login.windows.net/$Tenant"
Update-MSGraphEnvironment -AppId $ClientId -Quiet
Update-MSGraphEnvironment -AuthUrl $authority -Quiet
Connect-MSGraph -ClientSecret $ClientSecret -Quiet
} else {
Connect-MSGraph
}
#endregion
#region Main Script
########################################################
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
Function New-IntuneDocumentationAppRegistration(){
<#
.DESCRIPTION
This script will create an App registration(WPNinjas.eu Automatic Documentation) in Azure AD. Global Admin privileges are required during execution of this function. Afterwards the created clint secret can be used to execute the Intunde Documentation silently.
.EXAMPLE
$p = New-IntuneDocumentationAppRegistration
$p | fl
ClientID : d5cf6364-82f7-4024-9ac1-73a9fd2a6ec3
ClientSecret : S03AESdMlhLQIPYYw/cYtLkGkQS0H49jXh02AS6Ek0U=
ClientSecretExpiration : 21.07.2025 21:39:02
TenantId : d873f16a-73a2-4ccf-9d36-67b8243ab99a
.NOTES
Author: Thomas Kurth/baseVISION
Date: 21.7.2020
History
See Release Notes in Github.
#>
[CmdletBinding(SupportsShouldProcess, ConfirmImpact='Medium')]
Param(
)
## Manual Variable Definition
########################################################
#$DebugPreference = "Continue"
$ScriptName = "DocumentIntuneAppRegistration"


#region Initialization
########################################################
Write-Log "Start Script $Scriptname"

$AzureAD = Get-Module -Name AzureAD
if($AzureAD){
Write-Verbose -Message "AzureAD module is loaded."
} else {
Write-Warning -Message "AzureAD module is not loaded, please install by 'Install-Module AzureAD'."
}

#region Authentication
Connect-AzureAD
#endregion
#region Main Script
########################################################

$displayName = "WPNinjas.eu Automatic Documentation"

if (!(Get-AzureADApplication -SearchString $displayName)) {
$app = New-AzureADApplication -DisplayName $displayName `
-Homepage "https://localhost" `
-ReplyUrls "urn:ietf:wg:oauth:2.0:oob" `
-PublicClient $true


# create SPN for App Registration
Write-Debug ('Creating SPN for App Registration {0}' -f $displayName)

# create a password (spn key)
$startDate = Get-Date
$endDate = $startDate.AddYears(5)
$appPwd = New-AzureADApplicationPasswordCredential -ObjectId $app.ObjectId -CustomKeyIdentifier "Primary" -StartDate $startDate -EndDate $endDate

# create a service principal for your application
# you need this to be able to grant your application the required permission
$spForApp = New-AzureADServicePrincipal -AppId $app.AppId -PasswordCredentials @($appPwd)
} else {
Write-Output -InputObject ('App Registration {0} already exists' -f $displayName)
$app = Get-AzureADApplication -SearchString $displayName
}

$appPermissionsRequired = @('Policy.Read.All',
'Directory.Read.All',
'DeviceManagementServiceConfig.Read.All',
'DeviceManagementRBAC.Read.All',
'DeviceManagementManagedDevices.Read.All',
'DeviceManagementConfiguration.Read.All',
'DeviceManagementApps.Read.All',
'Device.Read.All')
$targetServicePrincipalName = 'Microsoft Graph'
Set-AzureADAppPermission -targetServicePrincipalName $targetServicePrincipalName -appPermissionsRequired $appPermissionsRequired -childApp $app -spForApp $spForApp


#endregion
#region Finishing
########################################################
[PSCustomObject]@{
ClientID = $app.AppId
ClientSecret = $appPwd.Value
ClientSecretExpiration = $appPwd.EndDate
TenantId = (Get-AzureADCurrentSessionInfo).TenantId
}

Write-Log "End Script $Scriptname"
#endregion
}
43 changes: 43 additions & 0 deletions PSModule/IntuneDocumentation/Internal/Set-AzureADAppPermission.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
Function Set-AzureADAppPermission
{
[CmdletBinding(SupportsShouldProcess, ConfirmImpact='Medium')]
param
(
[string] $targetServicePrincipalName,
$appPermissionsRequired,
$childApp,
$spForApp
)

$targetSp = Get-AzureADServicePrincipal -Filter "DisplayName eq '$($targetServicePrincipalName)'"

# Iterate Permissions array
Write-Output -InputObject ('Retrieve Role Assignments objects')
$RoleAssignments = @()
Foreach ($AppPermission in $appPermissionsRequired) {
$RoleAssignment = $targetSp.AppRoles | Where-Object { $_.Value -eq $AppPermission}
$RoleAssignments += $RoleAssignment
}

$ResourceAccessObjects = New-Object 'System.Collections.Generic.List[Microsoft.Open.AzureAD.Model.ResourceAccess]'
foreach ($RoleAssignment in $RoleAssignments) {
$resourceAccess = New-Object -TypeName "Microsoft.Open.AzureAD.Model.ResourceAccess"
$resourceAccess.Id = $RoleAssignment.Id
$resourceAccess.Type = 'Role'
$ResourceAccessObjects.Add($resourceAccess)
}
$requiredResourceAccess = New-Object -TypeName "Microsoft.Open.AzureAD.Model.RequiredResourceAccess"
$requiredResourceAccess.ResourceAppId = $targetSp.AppId
$requiredResourceAccess.ResourceAccess = $ResourceAccessObjects

# set the required resource access
Set-AzureADApplication -ObjectId $childApp.ObjectId -RequiredResourceAccess $requiredResourceAccess
Start-Sleep -s 1

# grant the required resource access
foreach ($RoleAssignment in $RoleAssignments) {
Write-Output -InputObject ('Granting admin consent for App Role: {0}' -f $($RoleAssignment.Value))
New-AzureADServiceAppRoleAssignment -ObjectId $spForApp.ObjectId -Id $RoleAssignment.Id -PrincipalId $spForApp.ObjectId -ResourceId $targetSp.ObjectId
Start-Sleep -s 1
}
}
12 changes: 6 additions & 6 deletions PSModule/IntuneDocumentation/IntuneDocumentation.psd1
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
#
# Generated by: Thomas Kurth
#
# Generated on: 15.06.2020
# Generated on: 21.07.2020
#

@{
Expand All @@ -12,7 +12,7 @@
RootModule = 'IntuneDocumentation.psm1'

# Version number of this module.
ModuleVersion = '2.0.15'
ModuleVersion = '2.0.16'

# Supported PSEditions
# CompatiblePSEditions = @()
Expand Down Expand Up @@ -70,7 +70,8 @@ RequiredModules = @('Microsoft.Graph.Intune',
# NestedModules = @()

# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
FunctionsToExport = 'Invoke-IntuneDocumentation'
FunctionsToExport = 'Invoke-IntuneDocumentation',
'New-IntuneDocumentationAppRegistration'

# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
CmdletsToExport = @()
Expand Down Expand Up @@ -108,10 +109,9 @@ PrivateData = @{
IconUri = 'https://github.com/ThomasKur/IntuneDocumentation/raw/master/Logo/IntuneDocumentationLogo.png'

# ReleaseNotes of this module
ReleaseNotes = ' 2.0.15 - 15.06.2020 - Thomas Kurth
ReleaseNotes = ' 2.0.16 - 21.07.2020 - Thomas Kurth
- Add documentation for Security Baseline.
- Add documentation for Custom Roles.
- Added possibility to run the documentation [in background](README.md#use-script-silently) with a custom App Registration
Expand Down
55 changes: 55 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,61 @@ Invoke-IntuneDocumentation -FullDocumentationPath c:\temp\IntuneDoc.docx -UseTra
```

### Use script silently

In the past I got requests that users would like to execute the Intune Documentation script silently. I have now extended the script by two new option and a new functions which can automatically create the App Registration in Azure AD for you.

#### Automatically Create App Registration

Your account requires Global Admin privileges to execute these commands and you need to have the AzureAD Module installed.

```powershell
$p = New-IntuneDocumentationAppRegistration
$p | fl
```

The following result will be displayed and can then be used. Safe the ClientSecret in your password vault.

```powershell
ClientID : d5cf6364-82f7-4024-9ac1-73a9fd2a6ec3
ClientSecret : S03AESdMlhLQIPYYw/cYtLkGkQS0H49jXh02AS6Ek0U=
ClientSecretExpiration : 21.07.2025 21:39:02
TenantId : d873f16a-73a2-4ccf-9d36-67b8243ab99a
```

#### Manually Create App Registration

You can follow the manual of Michael Niehaus https://oofhours.com/2019/11/29/app-based-authentication-with-intune/

But select also the following permission scopes:

- 'Policy.Read.All'
- 'Directory.Read.All'
- 'DeviceManagementServiceConfig.Read.All'
- 'DeviceManagementRBAC.Read.All'
- 'DeviceManagementManagedDevices.Read.All'
- 'DeviceManagementConfiguration.Read.All'
- 'DeviceManagementApps.Read.All'
- 'Device.Read.All'

#### Generate Documentation without user interaction

You can now call the Intune Documentation with the new parameters:

```powershell
Invoke-IntuneDocumentation `
-FullDocumentationPath c:\temp\IntuneDoc.docx `
-ClientId d5cf6364-82f7-4024-9ac1-73a9fd2a6ec3 `
-ClientSecret S03AESdMlhLQIPYYw/cYtLkGkQS0H49jXh02AS6Ek0U= `
-Tenant d873f16a-73a2-4ccf-9d36-67b8243ab99a
```

## Issues / Feedback

For any issues or feedback related to this module, please register for GitHub, and post your inquiry to this project's issue tracker.
Expand Down
4 changes: 4 additions & 0 deletions ReleaseNotes.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Release Notes

## 2.0.16 - 21.07.2020 - Thomas Kurth

- Added possibility to run the documentation [in background](README.md#use-script-silently) with a custom App Registration

## 2.0.15 - 15.06.2020 - Thomas Kurth

- Add documentation for Security Baseline.
Expand Down

0 comments on commit cd829bc

Please sign in to comment.