Thanks to this update, one of the examples of newly enabled scenarios would be querying the AIP admin log and regularly exporting it for processing in SIEM solutions to track certain activities, e.g. changes in the Super User configuration.
We will describe two options that can be used in this article – either using a certificate or a secret (Create an Azure AD app and service principal in the portal - Microsoft identity platform | Microsoft Docs).
At this point in time, the feature is limited to authenticate for performing read operations in the AIP Service.
This feature is available in AIPService PowerShell version 1.0.0.5 and can be found here PowerShell Gallery | AIPService 1.0.0.5.
How to authenticate to AIPService with client certificate
- Update AIPService PowerShell module
Run the following PowerShell command to update the AIPService module to version 1.0.0.5.
Update-Module AIPService
- Register new application
In portal.azure.com, switch to AAD and register a new application. The name of the application needs to be based on domain registered in AAD (see section “Custom domain names”), e.g. aipservice2.contoso.com.
- Add API permission for “Azure Rights Management Services”
In “API permissions”, select “Add a permission”, choose “Azure Rights Management Services” (on first page, i.e. “Microsoft APIs”). Choose “Application permissions”, selecting “Application.Read.All” and “Add permissions”. Select the newly added permission and “Grant admin Consent for <Tenant>”.
- Add a certificate for application
Identify a preexisting SSL client certificate or create a new one with the following command:
New-SelfSignedCertificate -CertStoreLocation "cert:\CurrentUser\My" -Subject "CN=SampleAuthCert" -KeySpec KeyExchange
Export the identified certificate without a private key to a local folder. In “Certificates & secrets”, select “Certificates” and upload the exported certificate. Copy the thumbprint of the newly uploaded certificate, this will be required for the next step.
- Update PowerShell script used for establishing AIPService connection
Perform the following changes in the PowerShell script below:
- Replace thumbprint with a thumbprint of the uploaded certificate.
- Switch to the “Overview” section of the newly registered application.
- Copy the “Application (client) ID” and replace it in the PowerShell script ($ApplicationId).
- Copy the “Directory (tenant) ID) and replace it in the PowerShell script ($TenantId).
$Thumbprint = 'AF54C307505E8BFCA7F0AE9ADEF599261704C4CFX'
$TenantId = '4714b877-9daf-45c3-b645-c9a66a48a50eX'
$ApplicationId = 'c78bdd33-b2db-4443-9dff-cee8a54340a4X'
Connect-AipService -CertificateThumbprint $Thumbprint -ApplicationId $ApplicationId -TenantId $TenantId -ServicePrincipal
- Connect to AIPService with PowerShell script
Run the updated script, expecting the following output:
A connection to the Azure Information Protection service was opened.
How to authenticate to AIPService with client secret
- Update AIPService PowerShell module
Run the following PowerShell command to update the AIPService module to version 1.0.0.5.
Update-Module AIPService
- Register new application
In portal.azure.com, switch to AAD and register a new application. The name of the application needs to be based on a domain registered in AAD (see section “Custom domain names”), e.g. aipservice2.contoso.com.
- Add API permission for “Azure Rights Management Services”
In “API permissions”, select “Add a permission”, choose “Azure Rights Management Services” (on the first page, i.e. “Microsoft APIs”). Choose “Application permissions”, selecting “Application.Read.All” and “Add permissions”. Select the newly added permission and “Grant admin Consent for <Tenant>”.
- Add client secret for application
In “Certificates & secrets”, select “Client secrets” and “New Client Secret”. Copy the value of the client secret, it will be required for the next step.
- Update PowerShell script used for establishing AIPService connection
Perform the following changes in the PowerShell script below:
- Replace the content of variable $SecretValue with the value of the client secret acquired in the last step. You may also provide the secret interactively, using option 1) of the script.
- Switch to the “Overview” section of the newly registered application.
- Copy the “Application (client) ID” and replace it in the PowerShell script ($ApplicationId).
- Copy the “Directory (tenant) ID) and replace it in the PowerShell script ($TenantId).
$TenantId = '4714b877-9daf-45c3-b645-c9a66a48a50eX'
$ApplicationId = 'c78bdd33-b2db-4443-9dff-cee8a54340a4X'
### Option 1), pass client secret interactively
### $Credential = Get-Credential -UserName $ApplicationId -Message "Please provide the secret"
### Option 2), put client secret in code (for testing only!)
$SecretValue = " a8Z7Q~wnKskpRjSbt0~CPgoLCiabgrjA9_39_X"
$Password = ConvertTo-SecureString $SecretValue -AsPlainText -Force
$Credential = New-Object System.Management.Automation.PSCredential ($ApplicationId, $Password )
Connect-AipService -Credential $Credential -TenantId $TenantId -ServicePrincipal
- Connect to AIPService with PowerShell script
Run the updated script, expecting the following output:
A connection to the Azure Information Protection service was opened.
Additional information
Logs about used authentication can be found in the AIP Admin Log (Get-AipServiceAdminLog (AIPService) | Microsoft Docs)
Authenticating via Service Principal works only with Read permissions due to security reasons.
Documentation:
Connect-AipService (AIPService) | Microsoft Docs
AIPService Module | Microsoft Docs
Use Azure PowerShell to create a service principal with a certificate