dgoldman-msft / psserviceprincipal

PowerShell module for creating and deleting enterprise and registered applications as well as SPN object (single and batch) for automation. This can be used as a facilitator for setting up Exchange PowerShell CBA

Description

This is a PowerShell module that will help in the creation (single and batch) enterprise, registered applications / service principals to be used with Microsoft application development. Application that connect to Office 365 will no longer be able to use Basic Authentication because it is being deprecated. This means that PowerShell will need a secure way to connect (interactively and automated) to Azure applications. For application workloads that require CBA (Certificate Based Authentication) (I.E Microsoft Exchange PowerShell) you can use this module to automate the onboarding of the necessary requirements that will allow you to connect using certificates. This method cuts down the 10-15 minutes of manual creation to just under a minute for single application creation.

NOTE: Due to incompatibility issues with the AzureAD module and PowerShell core at this time this module will only run on Windows PowerShell 5.X. If you try to run this on Module on PowerShell core it will partial run but you will not be able to create service principals and applications and will receive the following error: At this time AzureAD PowerShell module does not work on PowerShell Core. Please use PowerShell version 5 or 6 to create Registered Applications. Once the AzureAD module is PowerShell compatible this module will be updated accordingly.

Getting Started with PSServicePrincipal

1. First open a new PowerShell console as 'Administrator' and run the following command:

Install-Module -Name PSServicePrincipal

This will install the PSServicePrincipal module into your local PowerShell module path.

2. Run the following command:

Import-Module PSServicePrincipal

This will import the PSServicePrincipal module into your local PowerShell session. If you have any problems you can download the nupkg file directly from the PowerShell Gallery: https://www.powershellgallery.com/packages/PSServicePrincipal/1.0.11

At this point you have installed and loaded the PSServicePrincipal module and you are ready to create new service principals.

Example

1. Open PowerShell as an administrator
2. New-ServicePrincipalObject -DisplayName 'ExchangeCBAApp' -RegisteredApp -Cba -CreateSingleObject

In the above example we will create a new service principal object in the Azure tenant with a display name of 'ExchangeCBAApp', and we are passing in three argument switches. These three switches instruct the PSServicePrincipal module to do the following:

1. -RegisteredApp will create a registered Azure application (different from an Azure enterprise application).
2. -Cba will perform the following steps: a. Create a Self-Signed certificate (which will be stored locally as uploaded to the newly created Azure application. You just supply a DNS name and password for the certificate. b. Export the certificate (.pfx and .cer) files to your drive. c. Import the certificate to your local user certificate store. d. Import the certificate thumbprint to your newly created registered Azure tenant application. e. Apply the necessary api rights (Exchange.ManageAsApp) permissions to your application. (This is needed for unattended automation)
3. -CreateSingleObjectCreate will make sure we create a single service principal object (different from batch creation).

This will allow for a local interactive PowerShell session to connect to Exchange Online via CBA. If your intent is to use unattended automation you will need to copy the certificate from the local user certificate store to the computer's localMachine certificate store.

The last step you need to do is manually verify the settings and grant consent to the application to allow access.

1. Select the 'Azure Active Directory' option
2. Select 'App Registrations'
3. Select your application from the application list
4. Select Certificates & secrets and verify the certificate thumbprint has been added successfully.
5. Select 'API Permissions' to verify that 'Exchange.ManageAsApp' has been added successfully.
6. Select 'Grant Admin Consent for 'YourDomain' (Default Directory).

This will apply the permissions to the application in the tenant. Please allow up to 2 hours for Azure AD replication to take effect.

7. Add your application to an Azure security RBAC role that you want your application to have rights for. (This is based on your security model).

psserviceprincipal's Issues

[New-ServicePrincipal] Cannot find type [Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential]: verify that the assembly containing this type is loaded.

In Powershell verion 5.1.22621.963. script generates errors:

[10:03:22][New-ServicePrincipal] Creating SPN with ApplicationID
WARNING: [10:03:22][New-ServicePrincipal] Cannot find type
[Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential]: verify that the assembly containing this type is
loaded.
[10:03:22][] Checking current Role Assignment. Waiting for AD Replication
WARNING: [10:03:23][Add-RoleToSPN] Failed to: Applying role assignment: Adding Contributor role to SPN | Cannot
validate argument on parameter 'ApplicationId'. The argument is null or empty. Provide an argument that is not null or
empty, and then try the command again.
[10:03:23][Add-ExchangePermsToSPN.ps1] Exchange.ManageAsApp roll applied to application ExchangeCBAApp. To complete setup go to your application in the Azure portal and Grant Admin Consent.
WARNING: [10:03:24][Add-ExchangePermsToSPN.ps1] Cannot convert 'System.Object[]' to the type 'System.String' required
by parameter 'ObjectId'. Specified method is not supported.
[10:03:24][New-ServicePrincipalObject] Completed. Log saved to: "C:\Users\user\Documents\PSServiecPrincipal Logging".

Warnings / Errors on Running

[09:51:16][Add-ExchangePermsToSPN.ps1] Exchange.ManageAsApp roll applied to application ExOapponly2021. To complete setup go to your application in the Azure portal and Grant Admin Consent.
WARNING: [09:51:18][Add-ExchangePermsToSPN.ps1] Cannot convert 'System.Object[]' to the type 'System.String' required
by parameter 'ObjectId'. Specified method is not supported.

Thus step 5 "Select 'API Permissions' to verify that 'Exchange.ManageAsApp' has been added successfully." fails for obvious reasons. Should this really be a warning and not an outright error instead?

Additionally, there are a bunch of other warnings/errors eg (there were more):

WARNING: Upcoming breaking changes in the cmdlet 'Get-AzRoleAssignment' :
This cmdlet will use Microsoft Graph in Az 7.x and later.
Visit https://go.microsoft.com/fwlink/?linkid=2174792 for migration guide and breaking changes.
Note : Go to https://aka.ms/azps-changewarnings for steps to suppress this breaking change warning, and other
information on breaking changes in Azure PowerShell.
WARNING: Upcoming breaking changes in the cmdlet 'New-AzRoleAssignment' :
This cmdlet will use Microsoft Graph in Az 7.x and later.
Visit https://go.microsoft.com/fwlink/?linkid=2174792 for migration guide and breaking changes.
Note : Go to https://aka.ms/azps-changewarnings for steps to suppress this breaking change warning, and other
information on breaking changes in Azure PowerShell.
WARNING: [09:51:15][Add-RoleToSPN] Failed to: Applying role assignment: Adding Contributor role to SPN | Object
reference not set to an instance of an object.

Because I have a dev tenant this wasn't an issue, but not supporting MFA login also reduces the viability of the PS.

Ownership of ServicePrincipal

Hello could there maybe an option to create an owner (or multiple) for the ServicePrincipal?

BTW I love your work; saves me a ton of hour ;)

Does not support PowerShell 7

In trying to follow your instructions, I received the follow error: At this time AzureAD PowerShell module does not work on PowerShell Core. Please use PowerShell version 5 or 6 to create Registered Applications.