A while back I wrote a blog about the Secure Score and how to increase it. After that blog I got a lot more questions about documenting Secure Score with the Secure Application model.
To make handling the Secure Score easier, I’ve decided to make a PowerShell Module for this. The main reason for the module is to ease the complexity of changing the Secure Score settings over a lot of tenants. It’s a lot of small tweaks and settings. The module also tells you exactly what it’s going to do if you do not use the -confirmed switch, so you can check if you really wanna go on or not.
To keep in line with my other blogs, I’ll give some cool examples. First off we’ll document the Secure score both in HTML files and IT-Glue. I’ll blog about the remediation part later in the week, so I don’t overload everyone with information. 🙂
I do have to have a little disclaimer; the module is still a little rough around the edges. It’s a beta and I’m actively working on it. 🙂
To use the module, your Secure Application Model needs some extra permissions:
- Go to the Azure Portal.
- Click on Azure Active Directory, now click on “App Registrations”.
- Find your Secure App Model application. You can search based on the ApplicationID.
- Go to “API Permissions” and click Add a permission.
- Choose “Microsoft Graph” and “Application permission”.
- Search for “Security” and click on “SecurityEvents.Read.All”. Click on add permission.
- Search for “Security” and click on “and SecurityEvents.ReadWrite.All”. Click on add permission.
- Do the same for “Delegate Permissions”.
- Finally, click on “Grant Admin Consent for Company Name.
HTML version
######### Secrets #########
$ApplicationId = 'AppID'
$ApplicationSecret = 'AppSecret'
$TenantID = 'TenantID'
$RefreshToken = 'LongRefreshToken'
$ExchangeRefreshToken = 'LongExchangeToken'
$UPN = "UPN-Used-To-Generate-Tokens"
######### Secrets #########
install-module SecureScore
install-module PsWriteHTML
$Scores = get-securescore -AllTenants -upn $upn -ApplicationSecret $ApplicationSecret -ApplicationId $ApplicationId -RefreshToken $RefreshToken
foreach ($Score in $scores) {
New-HTML {
New-HTMLSection -HeaderText 'Scores compared'{
New-HTMLTable -DataTable $Score.scores.averageComparativeScores
}
New-HTMLSection -HeaderText "Score: $($score.Scores.currentScore) of $($score.Scores.maxScore)" {
New-HTMLTable -DataTable $Score.Scores.controlScores
}
} -FilePath "C:\temp\$($Score.TenantName) .html" -Online
}
And that’s it for the HTML version, lets move on to IT-Glue next.
IT-Glue version
The IT-Glue version creates the flexible asset for you, uploads the Secure Score for each client. It also looks-up all domains for the client so it can find the right client ID within IT-Glue.
######### Secrets #########
$ApplicationId = 'AppID'
$ApplicationSecret = 'AppSecret'
$TenantID = 'TenantID'
$RefreshToken = 'LongRefreshToken'
$ExchangeRefreshToken = 'LongExchangeToken'
$UPN = "UPN-Used-To-Generate-Tokens"
######### Secrets #########
########################## IT-Glue ############################
$APIKEy = "ITGAPIKEY"
$APIEndpoint = "https://api.eu.itglue.com"
$FlexAssetName = "O365 SecureScore v1"
$Description = "Secure Score v1."
########################## IT-Glue ############################
#Grabbing ITGlue Module and installing.
If (Get-Module -ListAvailable -Name "ITGlueAPI") {
Import-module ITGlueAPI
}
Else {
Install-Module ITGlueAPI -Force
Import-Module ITGlueAPI
}
#Settings IT-Glue logon information
Add-ITGlueBaseURI -base_uri $APIEndpoint
Add-ITGlueAPIKey $APIKEy
install-module SecureScore
install-module PsWriteHTML
write-host "Checking if Flexible Asset exists in IT-Glue." -foregroundColor green
$FilterID = (Get-ITGlueFlexibleAssetTypes -filter_name $FlexAssetName).data
if (!$FilterID) {
write-host "Does not exist, creating new." -foregroundColor green
$NewFlexAssetData =
@{
type = 'flexible-asset-types'
attributes = @{
name = $FlexAssetName
icon = 'sitemap'
description = $description
}
relationships = @{
"flexible-asset-fields" = @{
data = @(
@{
type = "flexible_asset_fields"
attributes = @{
order = 1
name = "Default Domain Name"
kind = "Text"
required = $true
"show-in-list" = $true
"use-for-title" = $true
}
},
@{
type = "flexible_asset_fields"
attributes = @{
order = 2
name = "TenantID"
kind = "Text"
required = $false
"show-in-list" = $false
}
},
@{
type = "flexible_asset_fields"
attributes = @{
order = 3
name = "Current Score"
kind = "Text"
required = $false
"show-in-list" = $false
}
},
@{
type = "flexible_asset_fields"
attributes = @{
order = 4
name = "Secure Score Comparetives"
kind = "Textbox"
required = $false
"show-in-list" = $false
}
},
@{
type = "flexible_asset_fields"
attributes = @{
order = 5
name = "Secure Score Settings"
kind = "Textbox"
required = $false
"show-in-list" = $false
}
}
)
}
}
}
New-ITGlueFlexibleAssetTypes -Data $NewFlexAssetData
$FilterID = (Get-ITGlueFlexibleAssetTypes -filter_name $FlexAssetName).data
}
write-host "Getting IT-Glue contact list" -ForegroundColor Green
$i = 0
$AllITGlueContacts = do {
$Contacts = (Get-ITGlueContacts -page_size 1000 -page_number $i).data.attributes
$i++
$Contacts
Write-Host "Retrieved $($Contacts.count) Contacts" -ForegroundColor Yellow
}while ($Contacts.count % 1000 -eq 0 -and $Contacts.count -ne 0)
write-host "Generating unique ID List" -ForegroundColor Green
$DomainList = foreach ($Contact in $AllITGlueContacts) {
$ITGDomain = ($contact.'contact-emails'.value -split "@")[1]
[PSCustomObject]@{
Domain = $ITGDomain
OrgID = $Contact.'organization-id'
Combined = "$($ITGDomain)$($Contact.'organization-id')"
}
}
$Scores = get-securescore -AllTenants -upn $upn -ApplicationSecret $ApplicationSecret -ApplicationId $ApplicationId -RefreshToken $RefreshToken
foreach ($Score in $scores) {
$FlexAssetBody =
@{
type = "flexible-assets"
attributes = @{
traits = @{
"default-domain-name" = $score.TenantName
"tenantid" = $score.TenantID
"current-score" = "$($score.Scores.currentScore) of $($score.Scores.maxScore)"
"secure-score-comparetives" = ($score.Scores.averageComparativeScores | convertto-html -Fragment | out-string) -replace "<th>", "<th style=`"background-color:#4CAF50`">"
"secure-score-settings" = ($score.Scores.controlScores | convertto-html -Fragment | out-string) -replace "<th>", "<th style=`"background-color:#4CAF50`">"
}
}
}
write-output " Finding $($score.TenantName) in IT-Glue"
$Domains = (Get-MsolDomain -TenantId $Score.TenantID).name
$ORGId = foreach ($Domain in $Domains) {
($domainList | Where-Object { $_.domain -eq $Domain }).'OrgID' | Select-Object -Unique
}
write-output " Uploading Secure Score for $($score.TenantName) into IT-Glue"
foreach ($org in $orgID) {
$ExistingFlexAsset = (Get-ITGlueFlexibleAssets -filter_flexible_asset_type_id $FilterID.id -filter_organization_id $org).data | Where-Object { $_.attributes.traits.tenantid -eq $score.TenantID }
#If the Asset does not exist, we edit the body to be in the form of a new asset, if not, we just upload.
if (!$ExistingFlexAsset) {
if ($FlexAssetBody.attributes.'organization-id') {
$FlexAssetBody.attributes.'organization-id' = $org
}
else {
$FlexAssetBody.attributes.add('organization-id', $org)
$FlexAssetBody.attributes.add('flexible-asset-type-id', $FilterID.id)
}
write-output " Creating new secure score for $($score.TenantName) into IT-Glue organisation $org"
New-ITGlueFlexibleAssets -data $FlexAssetBody
}
else {
write-output " Updating secure score $($score.TenantName) into IT-Glue organisation $org"
$ExistingFlexAsset = $ExistingFlexAsset | select-object -Last 1
Set-ITGlueFlexibleAssets -id $ExistingFlexAsset.id -data $FlexAssetBody
}
}
}
And that’s it! Somewhere this week I’ll also be talking about using the SecureScore module to apply the suggested remediation. As I said, those are still a little rough around the edges.
As always, Happy PowerShelling!
Thanks Kelvin for another great post!
A note for others here, you’ll need SecurityEvents.Read.All and SecurityEvents.ReadWrite.All graph permissions to get the Secure Score.
Also there’s a typo in the ITGlue script. This line should be
$Domains = (Get-MsolDomain -TenantId $Score.TenantID).name
Thanks rwllr! I’ll update the blog real quick with this info. 🙂
Very nice post! Definitly going to be taking advantage of it 🙂 I really appreciate the quantity and quality of your scripts.
On line 128, I would add the line -ErrorAction Continue, otherwise, if there is an old customer in there who have removed the Delegated Access Permissions, they will cause the command will fail for all the tenants.
I am struggling to find the UPN in line 7 of the HTML version, I ran the scripts from https://www.cyberdrain.com/connect-to-exchange-online-automated-when-mfa-is-enabled-using-the-secureapp-model/ and got all my secrets, but there is no UPN on there.
Thanks for all the scripts you have made so far, usually they run without problems!
The UPN is the UPN you used to generate the tokens, so if you logged in as “Hank@PropaneTank.com”, that’ll be the UPN to fill in there. 🙂
Pingback: Automating with PowerShell: Increasing the O365 Secure Score - CyberDrain
Hey Kelvin, thanks for another quality post! Struggling here for some reason; keep getting the following error when I try to run the line with ‘get-securescore’ in it:
New-PartnerAccessToken : A configuration issue is preventing authentication – check the error message from the server
for details.You can modify the configuration in the application registration portal. See
https://aka.ms/msal-net-invalid-client for details. Original exception: AADSTS7000215: Invalid client secret is
provided.
I made sure to grant the extra API permissions for my SAM in Azure AD. And I’ve used this same SAM app for other things that work properly (i.e. connecting to a customer’s Exchange Online PowerShell). Any thoughts?
Thanks Noah! You most likely are copy and pasting the information from previous blogs; there’s a tiny change. In this version you do not pass the Application Secret as a secure string. so you’ll need to remove the ” | ConvertTo-SecureString -Force -AsPlainText” part. 🙂
Hey Kelvin!
I know I’m dragging up an old post, but is it possible something has changed here? I’ve followed instructions exactly (very clearly checked permissions several times), and my tenants all give me 403 errors when retrieving the scores. Any idea where to start figuring that one out?
Thanks!