by

Utilizing the Workplace365/Alternate 2016 REST API half 2 buiding an Admin Runner utilizing AppOnly tokens

Utilizing the Workplace365/Alternate 2016 REST API half 2 buiding an Admin Runner utilizing AppOnly tokens That is half 2 in my REST sequence by which we are going to take a look at AppOnly tokens. These are the Tokens you’d look to make use of if you wish to write an utility or script that might entry each mailbox in an Workplace365 Tenant.  For an Admin or DevOps particular person taking a look at what they could wish to do with the brand new REST API that is helpful when your trying to write one thing that may tweak a config setting on all Mailboxes to adjust to a sure Group coverage (irrespective of how insane) or do some customized Merchandise job that is not supported in any of the Admin cmdlets.

To simplify AppOnly tokens as a lot as I can they’re an Oauth Entry token which can be requested utilizing Certificates Authentication. Then relying on what Utility permission scopes have been allowed for the app in Azure eg

your script or app will be capable to entry that exact Mailbox knowledge throughout all of the Mailboxes inside your tenant. In EWS in the event you understood how impersonation labored it is a sort of an equal however so much higher from a safety perspective. Eg if your simply writing a script that should maintain contacts in sync in a Mailbox (which I’ve seen and executed many occasions) then you may simply assign the “Read and write contacts in all mailboxes” scope to your utility and nothing else and that is all of your utility can do. With Impersonation you successfully gave full entry to Mailbox and which might then be doubtlessly exploited and was a lot derided by safety individuals on the whole.

Setup
 
There may be little bit of setup to do earlier than you need to use this which may be little sophisticated however I am going to attempt to simplify the perfect I can.

1. You’ll want to first create a Net Utility registration inside your tenant utilizing the Azure Administration Console (notice a local app will not work for this). https://docs.microsoft.com/en-us/azure/active-directory/active-directory-app-registration . For any such utility the SignIn and Auth url is not essential as we’re going to be utilizing certificates auth so you may simply use one thing like https://192.168.100.100:8000 eg

2. Configure the Utility permissions for what you need your utility to do eg the under display once more. For my check app I am going to be utilizing the “Read All Mailbox Setting” scope to create a script that learn the Oof Message and timezone setting from all mailboxes handed in. Delegated permission aren’t legitimate for any such App as they will not be scoped for the any such Entry token.

Ensure you click on save down the underside to make sure the adjustments you make are dedicated

3. Create a self signed certificates that might be used to signal the JWT (Java Net Token) requests. To make this straightforward in my Relaxation module I’ve create a cmdlet to do that utilizing the default New-SelfSignedCertificate Powershell cmd. Nonetheless this can solely work on Home windows 10 as a result of it requires the -provider change which is not out there on early O/S. Alternate options you need to use are MakeCert which there’s an instance of in https://msdn.microsoft.com/en-us/workplace/workplace365/howto/building-service-apps-in-office-365 or you may use OpenSSL

If you wish to use my cmdlet you want to make use of it like

Invoke-CreateSelfSignCert -CertName “yourCertNameMakeitdescriptive” -CertFileName c:tempyourcertFile.pfx -KeyFileName c:tempKeyCreds.txt

the place CertName must be self explanatory, CertFileName is the filename to your certificates (you may selected to go away It within the home windows CertStore however I’ve exported it to file for flexibility). -KeyFileName is a brief textual content file that may maintain the configuration data that must be copied in to the Utility manifest in Azure in step 4.

4. Replace the Utility manifest, from the Azure Console the place you configuration the appliance permissions in step2 you might want to choose the download manifest from the Handle Manifest possibility on the backside of the console eg

Upon getting download the manifest you might want to open that in a Textual content editor (or VSCode if in case you have it) and find the keycredentials entry

When you then open the KeyFileName that was created with Invoke-CreateSelfSignCert in step Three and lower and paste the all of the content material and exchange the [] in Keycredentials within the manifest you downloaded eg it ought to look one thing like this

 
Ensure when your pasting the info you do not wipe the comma after the worth as you’re going to get a parse error if you attempt to add the manifest. So when you save these change you click on add Manifest from the Handle Manifest button within the Azure console.

5. The very last thing you wish to do whereas within the Azure console is get your tenant ID data there are a variety of how to do that however the best is printed in https://help.workplace.com/en-us/article/Discover-your-Workplace-365-tenant-ID-6891b561-a52d-4ade-9f39-b492285e2c9b  (simply take a look at the URL if you modifying the appliance). You will have this TenantId for the Module Setup

PowerShell Module Setup

In my REST Script module I’ve a config part on the prime that holds the data wanted for producing the token. For App solely tokens you might want to setup the next variables

operate Get-AppSettings(){
        param(
       
        ) 
  Start
     choose ResourceURL,ClientId,redirectUrl,ClientSecret,x5t,TenantId
            $configObj.ResourceURL = “outlook.office.com”
            $configObj.ClientId = “084adbb3-f70c-498f-97a3-464e1f444d9a”
            $configObj.TenantId = “1c3a18bf-da31-4f6c-a404-2c06c9cf5ae4”
            $configObj.ClientSecret = “”
            $configObj.x5t = “3Y5+FU8x2tZ8DudO479K71ILQF8=”
            $configObj.ValidateForMinutes = 60
            return $configObj           
            
}

ResourceURL must be tremendous until you wish to entry the Graph API

ClientId must be the ClientId of your Utility in Manifest file you downloaded beforehand take the worth from appId which must be the primary line within the manifest

redirectURL is not used for AppOnly token

TenantId must be set to the worth you retrieved in step 5 above.

x5t must be set to the customKeyIdentifier that you just pasted into the KeyCredentials within the manifest file.

Testing

Upon getting all of the configuration executed to check whether it is working you employ the Get-AppOnlyToken cmdlet to create an app solely token

$Token  = Get-AppOnlyToken -CertFileName c:tempcertfile.pfx

When you then take a look at the contents of the $Token variable you must have both an error or a Token

Placing it to make use of

I’ve included one instance report within the REST Module that may work with AppOnly tokens. This produces a report of Mailbox setting utilizing the GetMailboxSetting op https://msdn.microsoft.com/workplace/workplace365/APi/mail-rest-operations#get-all-mailbox-settings

To run this you move in a set of Mailbox addresess you wish to run the report in opposition to (eg you may produce this utilizing Get-Mailbox) or use a CSV file or simply utilizing one thing like

$Mailboxes = @()
$Mailboxes += “one@domain.com”
$Mailboxes += “two@domain.com”

$report = Get-MailboxSettingsReport -Mailboxes $Mailboxes -CertFileName c:tempcertfile.pfx
$report | Export-Csv -NoTypeInformation -Path c:tempmbreport.csv

The REST PowerShell module may be discovered right here https://github.com/gscales/Powershell-Scripts/blob/grasp/RestHttpClientMod.ps1