Skip to content

Configuration Examples

Jump to bottom
Adam edited this page Feb 11, 2023 · 81 revisions

There a few ways you can configure this script to replace the stock Exchange Connector, the following will walk you through setting it up locally on your Workflow server through Task Scheduler, using the native Service Manager workflow engine, or using Azure Automation courtesy of a Cireson blog on the topic.

Regardless of the deployment strategy you choose, please ensure that:

  • When choosing your Incident, Service Request, Change Request, or Problem Request templates for either the primary or secondary mailboxes - do not use any Templates that come out of box with SCSM. Instead make sure you use or create your own custom Templates (e.g. Library -> Create Template). If you previously created your own custom Templates for use with the original Exchange Connector those are acceptable to use here.
  • The Active Directory PowerShell module is deployed alongside the connector as it is leveraged for Review Activities. This is available through the Remote System Administration Toolkit (RSAT) on any Windows Server.
    • Check if AD module is currently installed 
          Get-WindowsFeature RSAT-AD-PowerShell
    • Install the AD Module if isn't installed 
          Install-WindowsFeature RSAT-AD-PowerShell

Scenario 1: Task Scheduler

exampleTaskScheduler

The following example assumes the following:

  • This will be running directly on the SCSM Workflow Server as such the $scsmMGMTServer variable is set to "localhost"
  • SCSM 2012 R2 installed on Windows 2012 R2
  • Windows Authentication has been chosen for how the workflow account with authenticate to Exchange
  1. Decide where you'll place the script on the workflow server. You could create a new folder at C:\ or place this alongside the Service Manager directory, etc. In this example, I've created the path "C:\smletsExchangeConnector"
  2. In Task Scheduler, you can optionally create a New Folder underneath the parent "Task Scheduler Library" and in this example, I've created a folder called "PowerShell"
  3. Once you've decided the folder you'd like to place the task in, right click and choose "Create New Task". The following screenshots show how to configure the task to call the script to run every 5 minutes.

Give the task a name and description. More importantly, ensure the account that will run this job is your SCSM WF account, that is can run whether or not the user is logged on, and that the task is configured for Windows Server 2012 R2 exampleTaskScheduler

Next, we need to define task triggers. We'll execute it once at some specified time, repeat the task every 5 minutes for a duration of indefinitely, and ensure the task is marked as enabled. exampleTaskScheduler

Finally, we need to call the script. Our Action will be to start a program with a path to PowerShell and take the single -file argument to the location of the script. The following are those paths in my example that cut off in the screenshot

  • Program/script: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
  • Add arguments: -file "C:\smletsExchangeConnector\smletsExchangeConnector.ps1" exampleTaskScheduler

Scenario 2: Azure Automation

See Cireson Support Deploys Open Source SMLets Based Exchange Connector

Scenario 3: Exchange Online/Office 365 with OAuth

To make use of new OAuth 2.0 security protocols requires a newer version of Microsoft.Exchange.WebServices.dll. Both Exchange Connectors (SMLets/Microsoft) up until this point have made use of v1.2 of EWS. v2.2 is the latest version and required to use OAuth tokens. You can download it from the Microsoft Nuget gallery from here. Click "Download Package" to save it. Rename the file to be a .zip extension rather than .nupkg, then open the file, and extract out the lib\40 directory. It will contain the DLLs required.

1. Head into the Azure portal. Then Azure Active Directory to Register a new application for your Tenant.

2. Configure the Azure AD Application

  • Give the application a name (e.g. smexco, smlets exchange connector, etc.)
  • Choose "Accounts in this organizational directory only)"
  • Set the Redirect URI to "Public client/native (mobile & desktop).
  • Set the value to "urn:ietf:wg:oauth:2.0.oob"
  • Click "Register"

newApp02

3. Take note of the Application (Client) ID and Directory (Tenant) ID

03

4. (optional) Set the Logo and Home page URL to distinguish your application within your tenant. This makes it easy to distinguish the app if you registered other applications within your Azure tenant. You can use the following 215x215 png for the logo and https://github.com/AdhocAdam/smletsexchangeconnector as the URL

Capture 215x215

5. Go to the "Authentication" tab

  • Change "Allow public client flows" to Yes

Capture

6. Choose the APIs the app can leverage.

  • Select "API Permissions" and then click "Add a permission"
  • Select "Microsoft Graph", then choose "Delegated Permissions", search for "EWS.AccessAsUser.All"
  • Select it and then click "Add permissions"

azurepermissionconfig

7. At this point, an application has been registered unique to your Azure tenant. However in order for the connector read the inbox of your Service Manager workflow account. Users (in this case the SCSM WF account) must give their consent for the application to read their inbox. You must now perform 1 of the following 2 options:

  • Select the recently added "EWS.AccessAsUser.All" permissions select "Grant admin consent for org".
    • By choosing this approach, you are enabling EWS access for all users in your organization
  • Execute the following PowerShell and authenticate to the URL provided as the SCSM Workflow account.
    • By choosing this approach, EWS access is thus enabled only for Service Manager/the account that gives consent. If the account ever changes in the future, you would have to re-consent.
    #this is the Azure application/client id for the registered Azure Application
$clientId = ""
#this is your Azure tenant id
$tenantId = ""
$resource = "https://graph.microsoft.com/";

#build and make the request. Show the auth Code in the shell to enter on Microsoft's site.
$requestBody = @{
    client_id = $clientId
    resource = $resource
}
$response = Invoke-RestMethod -Method "POST" -Uri "https://login.microsoftonline.com/$tenantId/oauth2/devicecode" -Body $requestBody
Write-Output $response.message

NOTE: In either case from a security perspective - in order to read the mailbox of an account, you must know the username, password, unique Azure Tenant ID, and unique Azure Client/Application ID.

If you go with the second option in that only your Service Manager account has consented to the application. You can as the workflow account, head over to https://account.activedirectory.windowsazure.com/r#/applications. Here you should see the configured application in the list of its applications. It's possible that it may take a few minutes before it appears. Once you've consented via either option above, head into the General page on SMLets Exchange Connector Settings in the SCSM console.

exchangeonlineconfig

Here you'll need to:

Optional: Alternative Authentication:

If you opt to not use native the SCSM Workflow engine to run the connector, you must supply credentials to the connector for OAuth 2.0 to function. Again, if you are not using the SCSM Workflow Engine to run the script, you need to get the credentials in the script. As best practice, credentials should not be stored as plain text directly within the connector. So depending on the deployment approach (Task Scheduler, SMA, or Azure Automation) your configuration will vary.

  • Task Scheduler: Using the Microsoft Secrets Management module, you can store and retrieve secrets from the local credential vault.
#As an administrator on the server running the connector, run the following commands to update PowerShellGet and deploy the Microsoft Secrets Management module
Install-Module -Name "PowerShellGet" -Force
Update-Module -Name "PowerShellGet"
Install-Module -Name Microsoft.PowerShell.SecretsManagement -AllowPrerelease

Once you've done this, start PowerShell as the account running the Task. Then register the secret/password for the account with the following command

Set-Secret -Name "SMExcoSecret"

Once registered, update the $username and $password variables in the connector. This is similar to the screenshot below for SMA/Azure Automation.

$username = "usernameGoesHere"
$password = Get-Secret -Name "SMExcoSecret" -AsPlainText
  • SMA/Azure Automation: The credentials should be stored as Assets and accessed via a Get-AutomationPSCredential cmdlet. When the script runs it will reference the globally stored credentials. This approach requires you to edit two variables ($username and $password) directly within the PowerShell as seen here. Where 'Support-O365Mailbox' is the name of your Asset:
    get-automationpscredentialexample

This screenshot is borrowed from Cireson Support Deploys Open Source SMLets Based Exchange Connector

Scenario 4: Native Service Manager

As of SMLets Exchange Connector v3.0, you can quickly deploy the connector using a more familiar management pack installation experience. This approach simplifies installation of the connector and improves credential management by doing away with the need for Task Scheduler and the Secrets Management module as detailed in Scenario 3 above. With v3.0, credentials are now securely consumed from your stored SCSM Run as Accounts. So whether you're starting new or upgrading from a previous version, you can get going faster than ever before.

NOTE: Upon downloading, you may have to right-click on the zip file, go to Properties, and unblock the files. Failure to do so could prevent the workflow from running.

  1. Install the "SMLets.Exchange.Connector.mpb" Management Pack
    • Even if you are using a previous v2.x version, wherever you are currently running the script from will still continue to pull its configuration from the management pack
  2. Copy the "SMLets.Exchange.Connector.Resources.dll" to the installation directory for Service Manager on the Workflow server. The Workflow server is the first management server you deployed in your Service Manager environment. Depending on your version/upgrade path of Service Manager the following are some examples of those directories on said server:
    • C:\Program Files\Microsoft System Center 2012 R2\Service Manager
    • C:\Program Files\Microsoft System Center 2016\Service Manager
    • C:\Program Files\Microsoft System Center\Service Manager
  3. Configure the SMLets Exchange Connector settings in the SCSM Console. You can access this via Administration -> Settings.
    • On the General page, define which Run as Account you want to use to connect to Exchange. This should be the one you're using to currently process email
    • On the DLL page, provide the path to the SMLets Exchange Connector PowerShell script, Exchange Web Services DLL, etc.
    • On the Workflow page, define how often you want email to be processed in seconds. It's recommended that you run the connector no more than every 5 minutes (300 seconds).
    • When you're ready, enable the Workflow
      • If you've been running via Task Scheduler, SMA, or Azure Automation you'll want to disable that job before enabling the workflow here in SCSM.

For the truly interested, once the Workflow has been marked as enabled. A new Rule is created in the unsealed Service Manager Linking Framework Configuration management pack. This behavior (creating/modifying a Rule) is identical to how the stock Exchange Connector functions and the rule in this case looks like this -

<Rule ID="SMLets.Exchange.Connector.15d8b765a2f8b63ead14472f9b3c12f0" Enabled="true" Target="SCLibrary!Microsoft.SystemCenter.SubscriptionWorkflowTarget" ConfirmDelivery="false" Remotable="true" Priority="Normal" DiscardLevel="100">
<Category>PerformanceCollection</Category>
<DataSources>
    <DataSource ID="DS1" RunAs="SCLibrary!Microsoft.SystemCenter.DatabaseWriteActionAccount" TypeID="System!System.Scheduler">
    <Scheduler>
        <SimpleReccuringSchedule>
        <Interval Unit="Seconds">300</Interval>
        </SimpleReccuringSchedule>
        <ExcludeDates />
    </Scheduler>
    </DataSource>
</DataSources>
<WriteActions>
    <WriteAction ID="WA1" TypeID="Subscriptions!Microsoft.EnterpriseManagement.SystemCenter.Subscription.WindowsWorkflowTaskWriteAction">
    <Subscription>
        <WindowsWorkflowConfiguration>
        <AssemblyName>SMLets.Exchange.Connector.Resources</AssemblyName>
        <WorkflowTypeName>SMLets.Exchange.Connector.Resources.RunScript</WorkflowTypeName>
        <WorkflowParameters>
            <WorkflowParameter Name="ExchangeDomain" Type="string">$RunAs[Name="MP!AccountDomain"]/Domain$</WorkflowParameter>
            <WorkflowParameter Name="ExchangeUsername" Type="string">$RunAs[Name="MP!AccountUsername"]/UserName$</WorkflowParameter>
            <WorkflowParameter Name="ExchangePassword" Type="string">$RunAs[Name="MP!AccountPassword"]/Password$</WorkflowParameter>
            <WorkflowParameter Name="CiresonPortalDomain" Type="string">$RunAs[Name="MP!AccountDomain"]/Domain$</WorkflowParameter>
            <WorkflowParameter Name="CiresonPortalUsername" Type="string">$RunAs[Name="MP!AccountUsername"]/UserName$</WorkflowParameter>
            <WorkflowParameter Name="CiresonPortalPassword" Type="string">$RunAs[Name="MP!AccountPassword"]/Password$</WorkflowParameter>
        </WorkflowParameters>
        <RetryExceptions />
        <RetryDelaySeconds>60</RetryDelaySeconds>
        <MaximumRunningTimeSeconds>300</MaximumRunningTimeSeconds>
        </WindowsWorkflowConfiguration>
    </Subscription>
    </WriteAction>
</WriteActions>
</Rule>

The key difference being is that the WorkflowParameters will be different as Run as Account references will vary between organizations. It's also worth mentioning that regardless of whether or not you use the Cireson SCSM portal. Those values are set in the Settings UI by default so as to ensure there are not null values set here in the rule. This makes no difference in performance and the logic is ignored within the connector (PowerShell) if you have this integration disabled.

If you wish to uninstall the SMLets Exchange Connector workflow. Export this management pack, delete the rule, and then re-import it. You can confirm your change was successful by opening up the SMLets Exchange Connector Settings, navigating to the Workflow pane, and seeing that the rule is Disabled and the interval is 0. This is because the Rule no longer exists in the SCSMLFX unsealed management pack and as such, there are no values to read in the Settings UI.

Clone this wiki locally