Skip to main content

After this article

You’ll be able to connect the PowerShell connector to Lumos through the On-Premise Agent and use it to manage Exchange mailboxes, Exchange and Microsoft 365 groups, and Active Directory objects, or to run your own PowerShell scripts.

Capabilities

The PowerShell connector runs commands. It doesn’t sync users, groups, or activity from another system. The only account it reports is the account the connector runs as. Custom capabilities. These are the actions the PowerShell connector can perform. Remove User From All Groups doesn’t change dynamic distribution groups or Exchange role groups. It runs the Exchange groups and the Microsoft 365 groups as separate steps, so one step can succeed while the other fails. When that happens, Lumos reports the groups that were changed and the errors from the step that failed.

Required plan and roles

  • The On-Premise Agent. The connector runs on the Lumos On-Premise Agent. Without WinRM, commands run in Windows PowerShell on the agent’s own server, so that server must run Windows. With WinRM turned on, the agent sends commands to a remote Windows server instead.
  • An authentication method. Pick one of the following when you connect.
    • Basic uses a username and password. It’s the only method that works with WinRM.
    • Kerberos uses integrated Windows authentication. The username is optional and the password isn’t used, because the session runs as the account the Lumos Agent service runs as.
    • ServicePrincipalCertificate connects to Exchange Online with a Microsoft Entra app and a certificate, and needs no username or password. The agent must run on the same server as the Exchange PowerShell module, because this method doesn’t work with WinRM.
  • For Exchange on-premises actions. The Exchange PowerShell endpoint of your Exchange server, and an account that can run the Exchange cmdlets.
  • For Exchange Online actions. A Microsoft Entra app registration with the Exchange.ManageAsApp application permission and admin consent, the Exchange Administrator role assigned to the app, a certificate uploaded to the app, and the ExchangeOnlineManagement module installed on the server that runs the commands.
  • For Microsoft 365 group actions. The same Entra app with the Microsoft Graph User.Read.All application permission and admin consent, plus the Microsoft.Graph.Authentication, Microsoft.Graph.Groups, and Microsoft.Graph.Users modules.
  • For Move AD Object. The ActiveDirectory module (RSAT, or the AD DS server role) on the server that runs the commands. For cross-domain moves, the source and destination domain controllers must each be the RID Master of their domain. See Active Directory for the service account rights a cross-domain move needs.

Read-only access vs provisioning

Is read-only possible? Not in a useful way. The connector doesn’t sync accounts or permissions, so a connection that can’t run commands has nothing to do. What it needs. The account, app, and modules listed above for the actions you plan to use. You only need to set up the parts that match those actions. For example, if you only use Run Custom Command, you don’t need the Exchange Online settings. Watch out for. Every action runs with the rights of the account or app you connect with. Grant only the rights your actions need.

Instructions

Phase 1. Prepare the PowerShell host Do this on the server that runs the commands. That’s the On-Premise Agent’s server, or your WinRM server if you use WinRM.
  1. Open PowerShell as an administrator.
  2. For Exchange Online actions, install the Exchange Online module with Install-Module -Name ExchangeOnlineManagement -Force.
  3. For Microsoft 365 group actions, install the Graph modules with Install-Module -Name Microsoft.Graph.Authentication, Microsoft.Graph.Groups, Microsoft.Graph.Users -Force.
  4. For Move AD Object, install the Active Directory module through RSAT or the AD DS server role.
Phase 2. Find your Exchange on-premises endpoint (Exchange on-premises actions only)
  1. Open the Exchange Management Shell on your Exchange server.
  2. Run Get-PowerShellVirtualDirectory | Select Name,Server,InternalURL.
  3. Copy the InternalURL value, for example http://exserver.example.com/powershell/.
Phase 3. Set up a Microsoft Entra app (Exchange Online and Microsoft 365 group actions only)
  1. In the Microsoft Entra admin center, go to Entra ID → App registrations and click “New registration”.
  2. Name the app, select “Accounts in this organizational directory only”, and click “Register”.
  3. Copy the Application (client) ID from the app’s overview page.
  4. Go to API permissions and click “Add a permission”. Select “APIs my organization uses”, search for Office 365 Exchange Online, and select it.
  5. Select “Application permissions”, check Exchange.ManageAsApp, and click “Add permissions”.
  6. For Microsoft 365 group actions, click “Add a permission” again, select “Microsoft Graph”, then “Application permissions”, and add User.Read.All.
  7. Click “Grant admin consent” for your organization.
  8. Go to Entra ID → Roles & admins, open Exchange Administrator, click “Add assignments”, and add the app.
Phase 4. Create and upload a certificate (Exchange Online and Microsoft 365 group actions only)
  1. On the server that runs the commands, create a self-signed certificate in the Local Machine store, for example with New-SelfSignedCertificate -DnsName "lumos-exchange.example.com" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange.
  2. Give the Lumos Agent service account access to the private key. Open mmc.exe, add the Certificates snap-in for the Computer account, go to Personal → Certificates, right-click the certificate, select All Tasks → Manage Private Keys, and grant the service account Read.
  3. Export the certificate to a .cer file, for example with Export-Certificate.
  4. In the Entra app, go to Certificates & secrets → Certificates, upload the .cer file, and copy the Thumbprint.
Phase 5. Connect in Lumos
  1. Find the PowerShell card in your Lumos integrations. Reconnect an existing card or add a new one.
  2. Enter a “Unique Identifier” for this connection, such as exchange-prod. You can’t change it after you connect.
  3. Select the “Authentication Method”: Basic, Kerberos, or ServicePrincipalCertificate.
  4. For Basic, enter the “Username” (for a domain account, DOMAIN\username) and “Password”. For Kerberos, you can leave both blank.
  5. Under Microsoft Exchange Settings, fill in what your actions need.
    • “Exchange PowerShell Endpoint” is the InternalURL from Phase 2.
    • “Exchange Online Organization (onmicrosoft.com domain)” is your tenant’s primary domain, such as contoso.onmicrosoft.com. Find it under Entra ID → Overview.
    • “Exchange Online Application (client) ID” is the ID from Phase 3.
    • “Exchange Online Certificate Thumbprint” is the thumbprint from Phase 4.
  6. To run commands on a remote server, turn on “Use WinRM” under WinRM Settings (Optional) and enter the “WinRM Endpoint”, for example https://winrmserver.example.com:5986/wsman. Use HTTPS on port 5986 in production.
  7. Click “Connect”.

Run your own PowerShell script

Run Custom Command runs any script the PowerShell host can run, either on the On-Premise Agent’s server or on your WinRM server. This video shows an example configuration.
The action takes two inputs.
  • Script is the PowerShell script to run. It can span several lines.
  • Parameters are key-value pairs that become PowerShell variables. Keys must start with a letter or underscore and contain only letters, digits, and underscores. Reference them in the script as $key_name.
Lumos escapes each value and adds it to the top of the script as a variable before running it. For example, the script Enable-Mailbox -Identity $email with the parameters email set to jane.doe@example.com and account_id set to 12345 runs as:
Errors from your script come back to Lumos as PowerShell reported them.

Troubleshooting

“Username is required for basic authentication.” Basic authentication needs both a username and a password. Enter them, or switch to Kerberos. “The connector only supports basic authentication for WinRM.” WinRM works only with Basic. Turn off “Use WinRM” to use Kerberos or ServicePrincipalCertificate, which run on the agent’s own server. “WinRM endpoint is required when using WinRM.” Enter the “WinRM Endpoint”, or turn off “Use WinRM”. “WinRM call failed for endpoint…” Check that the server is reachable from the agent with Test-WSMan -ComputerName <server>, that the WinRM service is running (Get-Service WinRM), that the firewall allows port 5985 or 5986, and that the username uses the DOMAIN\username format. “ExchangeOnlineManagement module is not installed on this host.” Install the module on the server that runs the commands. With WinRM on, that’s the WinRM server, not the agent’s server. A “Missing Graph modules” error. The error lists the Microsoft Graph modules to install on the server that runs the commands. “ActiveDirectory module is not installed on this host.” Install RSAT or the AD DS server role on the server that runs the commands. Exchange Online actions fail to connect. Check that the organization, client ID, and thumbprint match the Entra app, that admin consent was granted for Exchange.ManageAsApp, and that the app has the Exchange Administrator role. Then check that the certificate is in cert:\LocalMachine\My (not the current user’s store), hasn’t expired, has a private key, and that the Lumos Agent service account can read the key. A command times out. A command running on the agent’s server stops after 25 minutes. When a mailbox or mailbox folder permission grant times out, or Exchange Online stops retrying, Lumos checks whether the permission was applied before reporting a failure.