Acquiring OAuth2 access tokens for automating Exchange Management Shell cmdlets


Overview

At present, there are no configurable permissions available for new Application Registrations in Azure Active Directory allowing to acquire OAuth2 tokens for automating Exchange Management Shell cmdlets. This work is currently being investigated by engineering and we hope to be in a position to provide such functionality in the future.

That said, there is a workaround which consists of using the well-known Exchange Management Shell app ID.

Application ID: a0c73c16-a7e3-4564-9a95-2bdf47383716
Redirect URL: urn:ietf:wg:oauth:2.0:oob

Requirements

Acquiring OAuth2 tokens using the well-known Exchange Management Shell app ID, requires the use an Exchange administrator account that can be used to authorise the requests.

How it works

In order to acquire a token, you will need to authorise an Exchange administrator account using the common endpoint and acquire an authorisation code. This means you will need to prompt the admin for a username and a password.

Once you've obtained the authorization code you can acquire an access token and pass the acquired token as a password in a PSCredential object, either to the New-PSSession cmdlet or when working with System.Management.Automation.Runspace objects.

Detailed steps

To simplify the process we recommend you use the Microsoft.IdentityModel.Clients.ActiveDirectory library. The following example demonstrates how to acquire a delegate token:

using Microsoft.IdentityModel.Clients.ActiveDirectory;

public static async Task<string> GetExchangeManagementShellToken()

{

try

{

AuthenticationContext authenticationContext = new Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext("https://login.microsoftonline.com/common", false);

AuthenticationResult authenticationResult = await authenticationContext.AcquireTokenAsync("https://outlook.office365.com", "a0c73c16-a7e3-4564-9a95-2bdf47383716", new Uri("urn:ietf:wg:oauth:2.0:oob"), new PlatformParameters(PromptBehavior.Always));

return authenticationResult.CreateAuthorizationHeader();

}

catch (Exception ex)

{

}

return
"";

}

The following example demonstrates how to use the newly acquired token:

using System.Management.Automation;

string token = GetExchangeManagementShellToken();

if (token != string.Empty)

{

PSCredential psCredential = new PSCredential("", token);

RunspaceConfiguration runspaceConfiguration = RunspaceConfiguration.Create();

WSManConnectionInfo wsManConnectionInfo = new WSManConnectionInfo("https://outlook.office365.com/PowerShell-LiveID", "http://schemas.microsoft.com/powershell/Microsoft.Exchange", psCredential);


using (Runspace runspace = RunspaceFactory.CreateRunspace(wsManConnectionInfo))

{


// your code goes here

}

}

Conclusion

You cannot register your own application in order to acquire OAuth2 tokens for automating Exchange Management Shell cmdlets from .Net or using PowerShell. This is because we do not currently offer a permissions model for doing so.

You can instead use the well-known Exchange Management Shell app ID if developing System.Management.Automation code or the Connect-EXOPSSession cmdlet if using PowerShell.

The only tokens available are delegate token and acquiring such a token requires explicitly prompting the administrator for a username and password. We are currently investigating the possibility of adding a permissions model to allow registering your own applications and generating both delegate and application tokens.

Notes

Since this is am app registration that is maintained by Microsoft, the only tokens you'll be able to acquire using this app registration are delegate tokens. Acquiring client secret or certificate-based application tokens is not possible.

Connect-EXOPSSession already uses this logic so if you're only trying to run Exchange Management Shell cmdlets, we recommend you use it instead of New-PSSession.

References

Connect-EXOPSSession

Microsoft.IdentityModel.Clients.ActiveDirectory

How to call Exchange 2010 cmdlet's using Remote Powershell in code

System.Management.Automation

Revisions

Revision type

Date Author Comments

Original

2018-09-07 Andrei Ghita
Comments (0)

Skip to main content