Runbook, run!

 

Dit blog heeft als doel het automatiseren van het verlenen van toegang tot een Enterprise Application omgeving, voor awareness trainingen en phishing tests.

De Enterprise Application is een online applicatie/website. In de settings daar is de optie geconfigureerd voor “Single sign on” op basis van SAML (Security Assertion Markup Language) met de Azure omgeving.

Hiertoe is er in de Azure een zgn. “Enterprise Application” geconfigureerd. Je kan je eigen applicatie registreren via “app registration” of uit een voorgekookte lijst uit de “Enterprice applications”. Een applicatie wordt dan geregistreerd in Azure AD en krijgt een “application object” voor de configuratie van toegang tot de applicatie. Daarnaast wordt er een unieke “Service Principal Object” geregistreerd onder “Enterprise applications”, met een subset van de configuratie opties.

Aan deze Enterprise Application kunnen “Users and groups” worden toegekend. Echter, dat is afhankelijk van het “Active Directory plan level”. Er zijn 4 “plans” voor Azure Active Directory, te weten Free, Office365 apps, Premium P1 en P2. Je krijgt onderstaande melding bij een Free plan, wat betekend dat je alleen users kunt toevoegen.

Dat is onhandig. Groups maken het mogelijk om nieuwe accounts automatisch toegang te geven tot de applicatie op basis van groepslidmaatschap. Daar heb je geen omkijken naar. In de situatie met een Azure Active Directory Free echter, zou je periodiek nieuwe gebruikers met de hand moeten toevoegen aan de “Users and groups” van de Enterprise Application. Een vervelende, bewerkelijke taak die foutgevoelig is. Er is gelukkig een oplossing.

Azure Runbooks

Dit zijn scripts opgeslagen in de Azure cloud en uitgevoerd door een Azure Automation account voorzien van de benodigde rollen en modules (in het geval van Powershell, Python wordt ook ondersteund). Eenmaal geconfigureerd en geplanned wordt dit op de achtergrond op een Hybrid Worker computer uitgevoerd tegen resources in de Azure tenant.

Benodigdheden

Benodigd zijn een Azure subscription, een Azure Automation Account, een eigen resource group (voor opslaan script en verbruiksminuten) en een script dat je wilt uitvoeren. De eerste 500 minuten/maand zijn inclusief in je abbonement.

Doe het volgende:

1.      Login op https://portal.azure.com

2.      Zoek “Automation accounts” op.

3.      Maak een Automation Account aan.

a.      Geef een passende naam op.

b.      Kies je abbonement.

c.      Maak een resource group aan.

d.      Wacht even tot hij is aangemaakt.

4.                                                 - Open het Azure Automation Account.
                         - Selecteer “Modules” om de nodige Powershell modules toe te voegen. Klik “Browse gallery”.
                                            - Installeer de “AzureAD” module.

Het Azure Automation Account is nu klaar voor gebruik.

Objection

Hoe authentiseer je de akties van het script in een Azure Runbook? Dit kan met het “Azure Run As” account. Dit is automatisch aangemaakt tijdens het maken van het Azure Automation account. Eerst moet het Run As account de juiste rechten krijgen, daarvoor is het unieke “Service Principal Object ID” nodig, te vinden onderaan het Run As account. Dit ObjectID gaan we gebruiken om de rollen aan het Run As account toe te wijzen.

Let’s role

Met onderstaande Powershell script ken ik de rol “User Administrator”, benodigd om users aan groups toe te kunnen voegen, toe aan het Run As Account van mijn eerder aangemaakte Automation Account.

# Verbind met AzureAD

Connect-AzureAD

# Stop het ObjectID van het Run As account in een variabele

$servicePrincipalObjectId = "f1d4a7b7-1111-4cf6-xxxx-xxxxxxxxxxxx"

#Ken de service principal de rol toe

Add-AzureADDirectoryRoleMember -ObjectId (Get-AzureADDirectoryRole | where-object {$_.DisplayName -eq "User Administrator"}).Objectid -RefObjectId $servicePrincipalObjectId

Users toekennen aan de Azure AD application met Powershell

We beginnen hier ook met het het ophalen van de Service Principal, maar dan van de Enterprise Application waar we users aan willen toekennen.

# Connect to Azure AD

Connect-AzureAD

# Get the service principal for the app you want to assign the user to

$servicePrincipal = Get-AzureADServicePrincipal -Filter "Displayname eq ' KnowBe4 Security Awareness Training"

Nu gaan we uit de Enterprise Application, de bestaande users opvragen:

# Get all users that are already assigned to the application

$existingUsers = Get-AzureADServiceAppRoleAssignment -all $true -ObjectId $servicePrincipal.Objectid | select -ExpandProperty PrincipalId

Nu vragen we ter vergelijk alle Azure AD users op met een licentie voor Office365 (want die hebben een mailbox en kunnen dus phishing tests ontvangen).

# Get all licensedUsers

$licensedUsers = Get-AzureADUser -all $true | Where-Object {$_.AssignedLicenses} | Select displayname,objectid

Nu kunnen we beiden variabelen met elkaar vergelijken.

# Compare lists

$newUsers = $licensedUsers | Where-Object { $_.ObjectId -notin $existingUsers }

In de variabele $newUsers zitten nu de lijst nieuwe gebruikers die nog niet zijn toegekend aan de Enterprise Application. Ik heb echter nog wat Service en Admin accounts die ik eruit wil filteren, die hoef ik namelijk niet te mailen. Ik geef een array van onwenselijke accounts op en voorzie die van het predicaat ObjectID.

# Users that should not be added, like service accounts, admin accounts etc.

[System.Collections.ArrayList]$ExcludedUsers = @()

$ExcludedObjectIDs = @( " xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", " xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", " xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", " xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", " xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", " xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", " xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

foreach ($obj in $ExcludedObjectIDs)

{

     $val = [pscustomobject]@{'ObjectId'=$obj}

     $ExcludedUsers.add($val) | Out-Null

     $val=$null

}

Nu ga ik de users in de variable $newUsers ontdoen van die in de variabele $ExcludedUsers.

# Filter out excludedusers

$RestUsers = $newUsers | Where-Object { $_.ObjectId -notin $ExcludedUsers.ObjectId }

In de variable $RestUsers zitten de nieuwe users die ik wil toevoegen aan de Enterprise Application. Dat doe ik met onderstaande

# Add residual users to the enterprise application.

ForEach ($user in $RestUsers) {

  Try {

    New-AzureADUserAppRoleAssignment -ObjectId $user.ObjectId -PrincipalId $user.ObjectId -ResourceId $servicePrincipal.ObjectId -Id $servicePrincipal.Approles[0].id -ErrorAction Stop

    [PSCustomObject]@{

        UserPrincipalName = $user.displayname

        AppliciationAssigned = $true

    }

  }

  catch {

    [PSCustomObject]@{

        UserPrincipalName = $user.displayname

        AppliciationAssigned = $false

    }

  }

} 

De losse stappen voegen we samen tot 1 script en dit kunnen we in het runbook plaatsen.

Runbook, run!

Ga naar het Automation Account en klik op “Runbooks”

 

1.      Klik “Create Runbook”

2.      Geef hem een betekenis volle naam

3.      Selecteer “Powershell” als het Runbook type

4.      Selecteer 5.1 als versie, de overigen worden (nu) nog als experimenteel weer gegeven.

5.      Klik “Create”.

 

Je krijgt nu een hele basic Powershell editor te zien. Je hebt onder CMDLETS de beschikbare Powershell cmdlets. Onder Runbooks een archiefje bestaande runbooks. Onder Assets zijn eerder geconfigureerde variabelen, connections, credentials en certificates, die je bijvoorbeeld vaker gebruikt. Je kan volstaan met het hierboven gemaakte script in plakken.

Teften

Je kan door op het “Test pane” te klikken een test run doen van het script. Het kan zijn dat je de volgorde verkeerd hebt, of een onbekende cmdlet gebruikt, dit komt er dan uit.

Saven

Als het script goed doorkomt, kan je hem saven. Daarmee overschrijf je geen bestaande versie.

Publishen

Om het script te kunnen gebruiken in een schedule, moet je het nu publishen.

On schedule

Op het runbook kan je nu een schedule plakken, als je het periodiek wilt draaien. Omdat dit om nieuwe users gaat heeft het in het begin van de week nog geen zin. Aan het eind ook niet, daarom heb ik de donderdag gekozen.

Je maakt eerst een algemeen “Schedule” aan onder “Schedule” met een algemene naam, bijv. “Weekly schedule”. Daarin zet je wanneer en hoelaat het schedule moet draaien, bijv. elke donderdag om 5 uur.

Done! Helaas heb ik nog geen mogelijkheid gezien om veilig (dus niet via Sendgrid) mailtjes te sturen welke users er zijn toegevoegd. Hier zal ik een nieuwe post aanwijden.