Automating Workspace ONE UEM API Authentication with PowerShell

Navigation

Introduction

When working with the Workspace ONE UEM API, authentication is a crucial first step before making any requests. To streamline this process, I’ve created UEMAuth.ps1, a PowerShell script that handles authentication by setting up environment variables, retrieving OAuth tokens, and generating the necessary headers for API calls.

This script is designed to be called by other automation scripts, ensuring they always have valid authentication credentials. It also simplifies scheduled tasks by storing encrypted credentials locally, reducing the need for manual intervention.

In this post, I’ll walk you through how UEMAuth.ps1 works, how to configure it for your environment, and how it helps automate API interactions with Workspace ONE UEM. You can find this script, along with other Workspace ONE automation tools, in my GitHub repo.

Why use UEMAuth.ps1?

Workspace ONE UEM requires OAuth authentication to interact with its API securely. Instead of hardcoding credentials in multiple scripts, UEMAuth.ps1 centralizes the authentication process, making it easier to manage and maintain. This script:

• Retrieves OAuth tokens dynamically.
• Generates the necessary headers for API calls.
• Supports different UEM data center regions.
• Encrypts and securely stores credentials for automated execution.

By using this script, you ensure that your API calls always have valid authentication headers, reducing the risk of authentication failures due to expired tokens.

Setting Up UEMAuth.ps1

Before running this script, please ensure the following:

• OAuth Client Setup: Create an OAuth Client for your Workspace One UEM tenant. For detailed instructions, refer to my post OAuth Client Creation in WS1 UEM.
• Environment Configuration: Configure a few variables to match your UEM environment. Open UEMAuth.ps1 in a text editor and update the following sections:

Define Your Environment Details

$global:ConsoleNumber = "NNN" # Replace NNN with your tenant number, e.g., 500
$global:Domain = "airwatchportals.com" # Change to 'awmdm.com' or your custom domain if applicable
$global:WS1url = $global:ASnumber + "." + $global:domain

💡You can confirm your AS number and domain via the UEM console by navigating to Groups & Settings > All Settings > System > Advanced > API > REST API where you’ll find the REST API URL in the format https://as<consolenumber>.awmdm.com/API

Specify Your Data Centre Region

Set the region based on your Workspace ONE UEM tenant’s data centre location:

$global:Region = "Australia" # Change to US, Canada, UK, Germany, India, Japan, Singapore, Australia, or Hong Kong

Allow PowerShell Script Execution

By default, PowerShell may prevent scripts from running due to execution policy restrictions. If you encounter an error when running UEMAuth.ps1, you may need to change the execution policy for the current PowerShell session. To allow the script to run, open PowerShell as an administrator and execute:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

This setting applies only to the current session and will revert once the session is closed, ensuring security remains intact. If you need to change the execution policy permanently, you can use:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

However, be cautious when modifying execution policies permanently, as it may introduce security risks.

Run the Script to Generate Credentials

For scheduled tasks or automation, you need to run the script manually once to generate an encrypted credentials file via a Powershell prompt:

.\UEMAuth.ps1

This will prompt you for your API credentials and store them securely in an XML file.

⚠️ The generated XML credentials file can only be used when running the script as the same user who originally created it. If you attempt to use the file under a different user account, authentication will fail. This ensures that credentials remain secure and cannot be accessed by other users on the system. If another user needs access, they must run the script and generate their own credentials file.

Script Breakdown

Checking for Stored Credentials

When executed, the script first checks for the encrypted credentials file. If it’s missing, the script prompts you to enter your credentials and saves them securely.

if (-Not (Test-Path $CredentialsFile)) {
    Write-Host "Error: The file '$CredentialsFile' is missing. Attempting to generate credentials..." -ForegroundColor Yellow
    Get-Credential | Export-CliXml -Path $CredentialsFile
    Write-Host "Credentials generation successful." -ForegroundColor Green
}

Retrieving OAuth Tokens

The script retrieves OAuth tokens from the appropriate Workspace ONE UEM authentication endpoint based on the selected region:

Function Get-OAuthUEMToken {
    $ClientID = $Credentials.GetNetworkCredential().UserName
    $ClientSecret = $Credentials.GetNetworkCredential().Password
    $TokenBody = @{
        grant_type    = "client_credentials"
        client_id     = $ClientID
        client_secret = $ClientSecret
    }
    $UEMResponse = Invoke-WebRequest -Method Post -Uri $TokenURL -Body $TokenBody -UseBasicParsing
    $UEMResponse = $UEMResponse | ConvertFrom-Json
    $OAuthToken = [string]$($UEMResponse.access_token)
    Return $OAuthToken
}

Generating API Headers

The script then creates headers containing the OAuth token for use in API calls:

Function Get-UEMHeader {
    [CmdletBinding()]
    Param(
        [Parameter(Mandatory = $true)]
        [string]$version
    )
    $Token = Get-OAuthUEMToken
    $global:UEMHeaders[$version] = @{
        "Authorization" = "Bearer $Token"
        "Accept"        = "application/xml;version=$global:version"
        "Content-Type"  = "$global:Content"
    }
    return $UEMHeader
}

Using UEMAuth.ps1 in your own Scripts

Once UEMAuth.ps1 has been configured and executed, the other EMMpowered Blog scripts can call it to retrieve authentication headers. But if you wish to use this with your own custom scripts, simply include the following line at the beginning of your scripts:

. .\UEMAuth.ps1

Then, use the generated headers in your API calls:

Invoke-RestMethod -Uri "https://$global:WS1url/API/resource" -Headers $global:UEMHeaders[1] -Method Get

This approach ensures that your API calls always use valid tokens, preventing authentication failures due to expired credentials.

Conclusion

Automating Workspace ONE UEM authentication simplifies API interactions and enhances security by centralising credential management. With UEMAuth.ps1, you can eliminate manual authentication steps and ensure your automation scripts run smoothly.

You can find this script, along with others on my GitHub page.