Microsoft Exchange Connector Application Guide Version 1.1 Nov 2016 1
License Agreement This software and the associated documentation are proprietary and confidential to EMC, are furnished under license, and may be used and copied only in accordance with the terms of such license and with the inclusion of the copyright notice below. This software and the documentation, and any copies thereof, may not be provided or otherwise made available to any other person. No title to or ownership of the software or documentation or any intellectual property rights thereto is hereby transferred. Any unauthorized use or reproduction of this software and the documentation may be subject to civil and/or criminal liability. This software is subject to change without notice and should not be construed as a commitment by EMC. Third-Party Licenses This product may include software developed by parties other than RSA. The text of the license agreements applicable to third-party software in this product may be viewed on the product documentation page on RSA SecurCare Online. By using this product, a user of this product agrees to be fully bound by terms of the license agreements. Note on Encryption Technologies This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when using, importing or exporting this product. Distribution Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2
CONTENTS Revision History... 4 Preface... 5 Supported RSA Identity Governance and Lifecycle Versions:... 5 Supported Microsoft Exchange Server versions:... 5 Audience... 5 What is covered in the Guide... 5 Introduction to PowerShell and PowerShell Cmdlets... 6 PowerShell Overview:... 6 PowerShell Cmdlets Overview:... 6 Prerequisites... 10 1. Configuring SSH PowerShell Server on windows for remote access... 10 2. Configuring RSAPowershellAgent on Windows for remote access... 18 Using RSA Identity Governance and Lifecycle SSH Microsoft Exchange Connector... 22 Configuration... 22 General... 22 Settings... 23 Capabilities... 23 Using RSA Identity Governance and Lifecycle Generic Powershell WebService Microsoft Exchange Connector... 34 Configuration... 34 General... 34 Settings... 35 Capabilities... 35 Tips & Troubleshooting... 45 Active Directory Connector Dependent Microsoft Exchange Connector... 47 COPYRIGHTS... 49 TRADEMARKS... 49 3
REVISION HISTORY Revision Number Version 1.0 Version 1.1 Description Microsoft Exchange Connector Added supported Microsoft Exchange versions 4
PREFACE This guide provides an overview of out of the box (OOTB) Microsoft Exchange Connector which uses SSH or RSAPowerShellAgent to communicate with Microsoft Exchange for provisioning and de-provisioning entities. This guide explains the required configurations, parameters, and different attributes mappings between the Connector and Microsoft Exchange supported system. Supported RSA Identity Governance and Lifecycle Versions: RSA Identity Management and Governance 6.8.1 and later RSA Identity Governance and Lifecycle 7.0.1 and later Supported Microsoft Exchange Server versions: Microsoft Exchange Server 2007, 2010 and 2013 Audience This guide is intended for the users of RSA Governance and Lifecycle, including security administrators. Any Microsoft Exchange system can be integrated with RSA Identity Governance and Lifecycle using these Connectors. Basic PowerShell cmdlets knowledge is an additional advantage. What is covered in the Guide An introduction to PowerShell and PowerShell Cmdlets helps understanding basics of this standard. How to configure RSA Identity Governance and Lifecycle Microsoft Exchange Connector. Tips and troubleshooting. 5
INTRODUCTION TO POWERSHELL AND POWERSHELL CMDLETS PowerShell Overview: Windows PowerShell is a task automation and configuration management framework from Microsoft, consisting of a command-line shell and associated scripting language built on the.net Framework. PowerShell provides full access to COM and WMI, enabling administrators to perform administrative tasks on both local and remote Windows systems Windows PowerShell can execute four kinds of named commands: cmdlets, which are.net programs designed to interact with PowerShell PowerShell scripts (files suffixed by.ps1) PowerShell functions standalone executable programs In PowerShell, administrative tasks are generally performed by cmdlets (pronounced command-lets), which are specialized.net classes implementing a particular operation. Sets of cmdlets may be combined into scripts, executables (which are standalone applications), or by instantiating regular.net classes (or WMI/COM Objects). These work by accessing data in different data stores, like the file system or registry, which are made available to the PowerShell runtime via Windows PowerShell providers. PowerShell Cmdlets Overview: Cmdlets are specialized commands in the PowerShell environment that implement specific functions. These are the native commands in the PowerShell stack. Cmdlets follow a Verb-Noun naming pattern (such as Get-Child Item), output their results as objects, known as collections thereof (including arrays), and can optionally receive input in that form. This makes them suitable for use as recipients in a pipeline. Whereas PowerShell allows arrays and other collections of objects to be written to the pipeline, cmdlets always process objects individually. For collections of objects, PowerShell invokes the cmdlet on each object in the collection, in sequence. Example: 1. Get-Command The Get-Command is one of the most useful cmdlets in PowerShell, as it will help you understand PowerShell and let you search for certain cmdlets. 6
2. Get-Process Get-Member Get-Member allows you to get the information on the objects that a cmdlets returns. However, Get- Member relies on PowerShell s pipeline feature. To demonstrate this, use the Get-Process cmdlet. 7
On the image above, the PowerShell output shows some of the properties at the top of each column. However, please note: While most frequently searched for properties appear in the list, not all properties are visible. The PowerShell does not show any methods that we are able to call on the object. To see the methods and properties we can pipe our output to Get-Member Cmdlet Parameters: Cmdlet parameters provide the mechanism that allows a cmdlet to accept input. Parameters can accept input directly from the command line, or from objects passed to the cmdlet through the pipeline. The arguments (also known as values) of these parameters can specify the input that the cmdlet accepts, how the cmdlet should perform its actions, and the data that the cmdlet returns to the pipeline. 8
Download: Download PowerShell Server v6 from http://www.powershellserver.com/download/. This is a free evaluation version with maximum 1 concurrent connection. If more than one concurrent connection is required, purchase the license from http://www.powershellserver.com/order/. 9
PREREQUISITES There are two ways to integrate, enable, and use a Microsoft Exchange Connector in an enterprise. 1. By configuring SSH PowerShell Server on Windows for remote access 2. By configuring RSAPowershellAgent on Windows for remote access 1. Configuring SSH PowerShell Server on windows for remote access To make sure that the Exchange Connector working, SSH PowerShell v6 Server and Microsoft Exchange should either be installed and running on the same machine or on the machine where there is command-line access to Microsoft Exchange Server. PowerShell v6 SSH Server: Deployment Architecture: SSH PowerShell Server can be deployed in two ways: 1. When PowerShell SSH Server and Microsoft Exchange Server reside on the same machine, and on different machines. a. When PowerShell SSH Server and Microsoft Exchange Server reside at same machine: i. By using SSH transport available, AFX will communicate to PowerShell Server and send the Microsoft Exchange PowerShell command for execution. b. When PowerShell SSH Server and Microsoft Exchange Server reside at different machines: 10
ii. By using SSH transport available, AFX will communicate to PowerShell Server and send the Microsoft Exchange PowerShell command for execution. Authentication: PowerShell Server supports three authentication mechanisms: Username/Password (NT), GSSAPI and Public Key Authentication. To work with RSA Identity Governance and Lifecycle, configure it with the Username/Password (NT) authentication. Installation: 1. Download the setup file (<setup>.exe) to a default download location or to a location given at the Download section. 2. Go to that download location, and double click on <setup>.exe. 3. Follow the Installation Wizard steps 11
12
13
14
15
4. Press Finish to complete the installation. There is no need for any customization. 5. Go to Start > All Programs > Powershell Server v6 6. Click Start powershell server. A server window will be opened. The first time running PowerShell Server, first switch to the Server Key tab to check/select the X.509 Digital Certificate to be used by the server to protect the SSH connections. By default, the setup will install and configure the application to use the included test certificate (testcert.pfx) generated through the installer. Alternatively, generate a new certificate, or select a previously generated one. Server Settings: 1. Open the server window. 2. Select checkbox Run as Windows Service 3. Go to the Other tab: 4. Under Log Options, check Write Log to a File to enable logging in. 5. Provide the appropriate location and filename. 6. Under Log Options, select the required Log Mode. RSA recommends using Verbose as the recommended mode. 16
7. Under Additional Settings, uncheck Enable Impersonation to disable it. 17
Authentication: 1. Go to the Security tab. 2. Under Authentication Settings, check Enable Password Authentication (NT authentication) as a method to authenticate the user. 3. Click Save Changes to save the changes. 4. Restart/start the server to ensure that the server-side installation and configurations are complete and the server is ready for use. 2. Configuring RSAPowershellAgent on Windows for remote access About the agent The RSAPowershellAgent is a WCF (Windows Communication Foundation) RESTful web-service hosted on a Windows service. The agent comes as a single executable with.exe.config file and a module file for the endpoints which would be needed. The module file currently comes for Forefront Identity Manager (FIM). The executable file can be run from the console with the options - install, uninstall and configure. o E.g. AveksaPowerShellAgent --install, AveksaPowerShellAgent --uninstall Pre-requisites 1. Install and launch OpenSSL v 0.9.8k or above. a. OpenSSL on a windows machine that can process cryptographic operations such as generation of a private key, certificate conversion, etc. 18
b. Access the official website of OpenSSL and Download Setup (openssl-setup.exe) or Binaries (openssl-bin.zip) of OpenSSL. i. If you have downloaded openssl-setup.exe, double click on it and follow default instructions ii. If you have downloaded openssl-bin.zip, unzip it c. The standard installation of OpenSSL under Windows is on "C:\OpenSSL-Win32" and the executable is stored in the sub-repertory "bin". To execute the program via the Windows command Prompt, provide one of the following paths: >C:\OpenSSL-Win32\bin\openssl.exe >C:\OpenSSL-Win64\bin\openssl.exe 2. Open a separate command prompt and go to openssl/bin. This second command prompt instance executes commands from following sections. 3. Generate the client certificate and install it on the server: a. The following command will generate a new private key and a new self-signed certificate. On the client machine (machine where RSA Identity Governance and Lifecycle is running) go to openssl/bin and execute: openssl req -new -newkey rsa:2048 -days 1825 -nodes -x509 -keyout <client_key_name>.key -out <client_cert_name>.cer -config openssl.cnf b. Save the generated.cer file as a DER encoded file i. Double click on the generated.cer certificate ii. Go to the Details tab iii. Click Copy to File. iv. Click Next on Certificate Export Wizard window v. Select DER encoded binary format and save at desired location. vi. On the command prompt run following command to convert generated file to.pem format: openssl x509 -in <certificate_generated_in_der_format>.cer -inform DER -out <desired_name>.pem -outform PEM c. Create a P12 file. This file will contain private key and the certification chain: The path to the file being generated would be the path of your keystore. The password would be the password specified while creating the key in section 3.1 default is changeit openssl pkcs12 -export -in <crt_generated_in_previous_command>.pem -inkey <key_name>.key -out <name>.p12 This file can be used with Microsoft Exchange. d. Install the certificate on the server. 4. Generate the server certificate and install it at the client (i.e. RSA Identity Governance and Lifecycle machine): a. On server machine (i.e. endpoint machine), go to the openssl/bin and execute: 19
makecert.exe -sr CurrentUser -ss My -a sha1 -n CN=<cert-name> -sky exchange -pe Make sure that the cert name is same as the machine name on which the agent is being installed. b. Make sure to later copy it into personal store for local machine. c. Export the certificate to DER file and copy and install it on the client side (i.e. machine on which the AFX would run). d. Use the keytool.exe utility $JAVA_HOME/jre/bin to import this certificate to a trust-store. e. Create a new trust-store file or simply add it to java trust-store file: $JAVA_HOME/jre/lib/security/cacerts To do this, navigate to C:\Program Files\Java\jre6\lib\security and execute the following command:../../bin/keytool -import -alias myalias -file <server certificate name : should be same as the server name used when installing the agent> -keystore cacerts storepass changeit f. Install this certificate on the client RSA Identity Governance and Lifecycle machine. 5. When creating a Microsoft Exchange Connector, use the following path of the trust-store and use changeit as a password a. C:\Program Files\Java\jre6\lib\security\cacerts Installing the Agent: 1. Unzip the installer provided. 2. Inside the modules directory, find a.psm1 file. Copy this directory to a location on the endpoint Server (e.g. FIM, Microsoft Exchange). Note the path where it was copied. 3. Open the command prompt as an administrator. 4. Go to the directory where the agent is present using command prompt 5. Type AveksaPowerShellAgent --install 6. Enter the details as prompted on the console. 7. In the last question for installation, Enter the full path of directory enter the path on FIM server noted down from Step 2 of this section. 8. After the installation is complete, go to the Services console. 9. The service named AveksaPowerShellAgent should now be running. After Agent Installation: 1. Go to the Services console and to AveksaPowerShellAgent. 2. Double click it and go to the Logon tab. 3. Select Computer accounts option and enter <Domain>\<Administrator User Name> and domain admin password. 4. Restart the service. 5. Open the command prompt as an administrator. 6. Run the following command to configure the Port with an SSL Certificate: netsh http add sslcert ipport=<ip address of machine where agent is installed>:<port number which you have entered while installation> certhash=<thumbprint of the server certificate without any whitespaces>} appid={97d271d8-f3cc-4eac-a873-6638b8879bb9} 20
a. Example: if the Agent is installed on 172.30.30.11 and port number is 9007, the command would look like (certhash will be different): netsh http add sslcert ipport=172.30.30.111:9007 certhash=efda2ea8f0fbf4a73252206a92b0fc339072ba51 appid={97d271d8-f3cc-4eac-a873-6638b8879bb9} b. Note: You will need.net framework 4.0 for this agent to execute commands on Microsoft Exchange 2010 machine. Currently, for Microsoft Exchange, the client certificate based authentication does not work. Although you should continue to follow the steps to create a client certificate, it would not be used. Still provide the path of.p12 file to Connector, which should work with the path same as that of the trust-store. Deployment Architecture: RSAPowerShellAgent and Microsoft Exchange Server will reside in the same machine. By using the Generic PowerShell WebSevice transport available, AFX will communicate with RSAPowerShellAgent and send the Microsoft Exchange PowerShell command for execution. 21
USING RSA IDENTITY GOVERNANCE AND LIFECYCLE SSH MICROSOFT EXCHANGE CONNECTOR This Connector can be used to communicate and to provision data to Microsoft Exchange Server. Configuration The configuration of the Connector is completed through a number of screens. This section will help you fill in the values for each screen. The Connector is created through the following three sections: general, settings, and capabilities. General The general section features details about the Connector, such as the name, and type of the Connector. Refer to the table below to configure General tab: Name <Connector instance name> Description <Connector instance description> Server Select available AFX server Connector Template Under group type SSH: Microsoft Exchange 2007/ Microsoft Exchange 2010/ Microsoft Exchange 2013 State Test/Active Note that on satisfactory Connector testing, change the state to Active. No automated provisioning will occur while in the Test state. It is recommended to test all enabled commands using the Test Connector Settings and check Connector Capabilities prior to changing to the Active state. Export As Template Use this field to name this Connector export zip file, used while exporting the Connector instance 22
Settings The connection settings required to connect the two entities, RSA Identity Governance and Lifecycle and the End-point Application, are listed below. Refer to the table below to configure the Settings tab: Connection Details Server Host <Host name or an IP address of the host where Microsoft Exchange Server and PowerShell SSH Server are installed> Port <The port where the PowerShell SSH Server is listening. Default value: 22> Timeout(milliseconds) <Connection timeout (milliseconds)>default : 300000 Login Name <The Login Name of the administrator user of the host where Microsoft Exchange Server and PowerShell SSH Server are installed> Password <Password for Login Name> Capabilities This tab has a list of capabilities supported by the Microsoft Exchange Connector. For the Exchange AFX Connector, use the term Mailbox instead of Account on AFX User Interface. All of the operations are supported and performed on Microsoft Exchange Mailbox, such as: CreateAccount: creates a mailbox DeleteAccount: deletes a mailbox EnableAccount: enables a mailbox DisableAccount: disables a mailbox UpdateAccount: updates a mailbox MoveAccount: moves a mailbox from one database to another Each capability listed above has the same configurations and can be changed according to the executable PowerShell commands. Refer to the section below to configure the capabilities. 23
Capabilities Settings For any available capability, the settings require that a user: Provide input parameters. Provide Exchange PowerShell command. Command : CreateAccount Command Name Limitations CreateAccount Microsoft Exchange is Active Directory dependent application. To create an account/mailbox at Exchange, first there should be an account in Active Directory Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes. Is the parameter encrypted? No 24
Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Parameter Name Database Type String Default Is the parameter required? Yes Is the parameter encrypted? No Display Name Database Mapping Mailbox Database name. We need to provide default value for this parameter Description Mailbox database name Command Code Exchange Command Add-PSSnapin Microsoft.Exchange.Management.PowerShell.Admin 2>&1 Write- Host; if($?) {Enable-Mailbox '${Identity}' -Database '${Database}' 2>&1 Write- Host;} Note: 1. In the example mentioned here, Snap-in is required as example refers to a SSH based Connector. Snap-in added here is of Exchange 2013. If Exchange 2007 or Exchange 2010 is being configured, please change Snap-in name. E.g. For Exchange 2007 : Microsoft.Exchange.Management.PowerShell.Admin, For 25
Exchange 2010 : Microsoft.Exchange.Management.PowerShell.E2010 2. If RSAPowerShellAgent based Connector is being configured, Snap-in is not required. Command : DeleteAccount Command Name Limitations DeleteAccount Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes Is the parameter encrypted? No Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Command Code Exchange Command Add-PSSnapin Microsoft.Exchange.Management.PowerShell.Admin 2>&1 Write- 26
Host; if($?) {Disable-Mailbox '${Identity}' -Confirm:$False 2>&1 Write-Host;} Note: 1. In the example mentioned here, Snap-in is required as example refers to a SSH based Connector. Snap-in added here is of Exchange 2013. If Exchange 2007 or Exchange 2010 is being configured, please change Snap-in name. E.g. For Exchange 2007 : Microsoft.Exchange.Management.PowerShell.Admin, For Exchange 2010 : Microsoft.Exchange.Management.PowerShell.E2010 2. If RSAPowerShellAgent based Connector is being configured, Snap-in is not required. Command: EnableAccount Command Name Limitations EnableAccount Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes. Is the parameter encrypted? No Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name 27
Parameter Name Database Type String Default Is the parameter required? Yes Is the parameter encrypted? No Display Name Database Mapping Mailbox Database name. We need to provide default value for this parameter Description Mailbox database name Command Code Exchange Command Add-PSSnapin Microsoft.Exchange.Management.PowerShell.Admin 2>&1 Write- Host; if($?) {Enable-Mailbox '${Identity}' -Database '${Database}' 2>&1 Write- Host;} Note: 1. In the example mentioned here, Snap-in is required as example refers to a SSH based Connector. Snap-in added here is of Exchange 2013. If Exchange 2007 or Exchange 2010 is being configured, please change Snap-in name. E.g. For Exchange 2007 : Microsoft.Exchange.Management.PowerShell.Admin, For Exchange 2010 : Microsoft.Exchange.Management.PowerShell.E2010 2. If RSAPowerShellAgent based Connector is being configured, Snap-in is not required. 28
Command : DisableAccount Command Name Limitations DisableAccount Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes Is the parameter encrypted? No Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Command Code Exchange Command Add-PSSnapin Microsoft.Exchange.Management.PowerShell.Admin 2>&1 Write- Host; if($?) {Disable-Mailbox '${Identity}' -Confirm:$False 2>&1 Write-Host;} Note: 1. In the example mentioned here, Snap-in is required as example refers to a SSH based Connector. Snap-in added here is of Exchange 2013. If Exchange 2007 or Exchange 2010 is being configured, please change Snap-in name. 29
E.g. For Exchange 2007 : Microsoft.Exchange.Management.PowerShell.Admin, For Exchange 2010 : Microsoft.Exchange.Management.PowerShell.E2010 2. If RSAPowerShellAgent based Connector is being configured, Snap-in is not required. Command: UpdateAccount Command Name Limitations UpdateAccount Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes. Is the parameter encrypted? No Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Parameter Name ForwardingAddress 30
Type String Default Is the parameter required? Yes Is the parameter encrypted? No Display Name Forwarding Address Mapping ${Account.Name} Description Forwarding address i.e. alias to which mails should be forwarded Command Code Exchange Command Add-PSSnapin Microsoft.Exchange.Management.PowerShell.Admin 2>&1 Write- Host; if($?) {Set-Mailbox '${Identity}' -ForwardingAddress '${ForwardingAddress}' 2>&1 Write-Host;} Note: 1. In the example mentioned here, Snap-in is required as example refers to a SSH based Connector. Snap-in added here is of Exchange 2013. If Exchange 2007 or Exchange 2010 is being configured, please change Snap-in name. E.g. For Exchange 2007 : Microsoft.Exchange.Management.PowerShell.Admin, For Exchange 2010 : Microsoft.Exchange.Management.PowerShell.E2010 2. If RSAPowerShellAgent based Connector is being configured, Snap-in is not required. Command : MoveAccount Command Name Limitations MoveAccount 31
Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes. Is the parameter encrypted? No Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Parameter Name Database Type String Default Is the parameter required? Yes Is the parameter encrypted? No Display Name Database 32
Mapping Name of the target database where you want to move mailbox (e.g. New Mailbox Database, EN12434 Mailbox Database etc.) Description A target mailbox database name Command Code Exchange Command Add-PSSnapin Microsoft.Exchange.Management.PowerShell.Admin 2>&1 Write- Host; if($?) {Move-Mailbox '${Identity}' -TargetDatabase '${Database}' - Confirm:$False 2>&1 Write-Host;} Note: 1. In the example mentioned here, Snap-in is required as example refers to a SSH based Connector. Snap-in added here is of Exchange 2013. If Exchange 2007 or Exchange 2010 is being configured, please change Snap-in name. E.g. For Exchange 2007 : Microsoft.Exchange.Management.PowerShell.Admin, For Exchange 2010 : Microsoft.Exchange.Management.PowerShell.E2010 2. If RSAPowerShellAgent based Connector is being configured, Snap-in is not required. 33
USING RSA IDENTITY GOVERNANCE AND LIFECYCLE GENERIC POWERSHELL WEBSERVICE MICROSOFT EXCHANGE CONNECTOR This Connector can be used to communicate and to provision data to Microsoft Exchange Server. Configuration The configuration of the Connector is completed through a number of screens. This section will help you fill in the values for each screen. The Connector is created through the following three sections: general, settings, and capabilities. General The general section features details about the Connector, such as the name, and type of the Connector. Refer to the table below to configure General tab: Name <Connector instance name> Description <Connector instance description> Server Select available AFX server Connector Template Under group type Generic-Powershell-WebService : Microsoft Exchange 2007/ Microsoft Exchange 2010/ Microsoft Exchange 2013 State Test/Active Note that on satisfactory Connector testing, change the state to Active. No automated provisioning will occur while in the Test state. It is recommended to test all enabled commands using the Test Connector Settings and check Connector Capabilities prior to changing to the Active state. Export As Template Use this field to define name of this Connector export zip file, it will get used while exporting Connector instance 34
Settings The connection settings required to connect the two entities, RSA Identity Governance and Lifecycle and the End-point Application, are listed below. Refer to the table below to configure the Settings tab: Connection Details Endpoint Type <Type of the endpoint where command(s) would be running e.g. FIM, exchange etc.> Powershell Host Name <Host name or an IP address of the host where PowerShell Agent is running> Powershell Port <The port where the PowerShell Agent is listening> Trust-Store Path <Path for the trust-store where the agent certificate has been added> Trust-Store Password <Password of the trust-store where the agent certificate has been added> Key-Store Path <Path for the key-store where the client (connector) certificate has been added> Key-Store Password <Password of the key-store where the client (connector) certificate has been added> Capabilities This tab has a list of capabilities supported by the Microsoft Exchange Connector. For the Exchange AFX Connector, use the term Mailbox instead of Account on AFX User Interface. All of the operations are supported and performed on Microsoft Exchange Mailbox, such as: CreateAccount: creates a mailbox DeleteAccount: deletes a mailbox EnableAccount: enables a mailbox DisableAccount: disables a mailbox UpdateAccount: updates a mailbox MoveAccount: moves a mailbox from one database to another Each capability listed above has the same configurations and can be changed according to the executable PowerShell commands. Refer to the section below to configure the capabilities. 35
Capabilities Settings For any available capability, the settings require that a user: Provide input parameters. Provide Exchange PowerShell command. Command: CreateAccount Command Name Limitations CreateAccount Microsoft Exchange is Active Directory dependent application. To create an account/mailbox at Exchange, first there should be an account in Active Directory Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes. Is the parameter encrypted? No 36
Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Parameter Name Database Type String Default Is the parameter required? Yes Is the parameter encrypted? No Display Name Database Mapping Mailbox Database name. We need to provide defaultvalue for this parameter Description Mailbox database name Command Code Exchange Command Enable-Mailbox '${Identity}' -Database '${Database}' Note: Powershell command to add the Snap-in is not required for Powershell agent based connector. 37
Command: DeleteAccount Command Name Limitations DeleteAccount Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes Is the parameter encrypted? No Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Command Code Exchange Command Disable-Mailbox '${Identity}' -Confirm:$False Note: Powershell command to add the Snap-in is not required for Powershell agent based connector. 38
Command : EnableAccount Command Name Limitations EnableAccount Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes. Is the parameter encrypted? No Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Parameter Name Database Type String Default 39
Is the parameter required? Yes Is the parameter encrypted? No Display Name Database Mapping Mailbox Database name. We need to provide default value for this parameter Description Mailbox database name Command Code Exchange Command Enable-Mailbox '${Identity}' -Database '${Database}' Note: Powershell command to add the Snap-in is not required for Powershell agent based connector. Command: DisableAccount Command Name Limitations DisableAccount Input Parameters Parameter Name Identity Type String Default 40
Is the parameter required? Yes Is the parameter encrypted? No Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Command Code Exchange Command Disable-Mailbox '${Identity}' -Confirm:$False Note: Powershell command to add the Snap-in is not required for Powershell agent based connector. Command : UpdateAccount Command Name Limitations UpdateAccount Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes. 41
Is the parameter encrypted? No Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Parameter Name ForwardingAddress Type String Default Is the parameter required? Yes Is the parameter encrypted? No Display Name Forwarding Address Mapping ${Account.Name} Description Forwarding address i.e. alias to which mails should be forwarded Command Code Exchange Command Set-Mailbox '${Identity}' -ForwardingAddress '${ForwardingAddress}' Note: Powershell command to add the Snap-in is not required for Powershell agent based connector. 42
Command:MoveAccount Command Name Limitations MoveAccount Input Parameters Parameter Name Identity Type String Default Is the parameter required? Yes. Is the parameter encrypted? No Display Name Identity Mapping ${Account.Name} Description Identity/Mailbox name Parameter Name Database Type String Default Is the parameter required? Yes 43
Is the parameter encrypted? No Display Name Database Mapping Name of the target database where you want to move mailbox (e.g. New Mailbox Database, EN12434 Mailbox Database etc.) Description A target mailbox database name Command Code Exchange Command For Microsoft Exchange 2007 : Move-Mailbox '${Identity}' -TargetDatabase '${Database}' -Confirm:$False For Microsoft Exchange 2010 and 2013 : cd 'C:\\Program Files\\Microsoft\\Exchange Server\\V14\\Scripts';.\\MoveMailbox.ps1 -Identity '${Identity}' -TargetDatabase '${Database}' Note: Powershell command to add the Snap-in is not required for Powershell agent based connector. 44
TIPS & TROUBLESHOOTING 1. How Does Microsoft Exchange Connector parse error code? Does it parse the error code at all? Microsoft Exchange Connector uses SSH transport. If you see "SSH.mule.xml" a flow is written which will process the exit status and respond back. There it checks ssh.outexit_status=0 and if condition is true, it will set the AFX_ERROR_CODE=0 i.e. success. 2. The Exchange Connectors only have non-standard verbs. Do they always work with form fulfillment workflows because they won t work with the normal CRs? If you check "Microsoft-Exchange.AFX.xml" you can see the verbs used for provisioning. The description for the command is written according to the exchange terminologies. In other words, if the description is "create a mailbox" at back-end, the standard "CreateAccount" verb is executed. CreateAccount (create a mailbox) and DeleteAccount (delete a mailbox) will work with the normal CRs. The remaining commands, EnableAccount, DisableAccount, UpdateAccount, MoveAccount, are supposed to work with form fulfillment workflows. 3. The customer wants to execute a different command which is not provided as a default with Microsoft Exchange Connector (for example, "Set-CASMailbox '${Identity}' -ActiveSyncEnabled '${ActiveSync}' -OWAEnabled '${OWAEnabled}' -PopEnabled '${POP3}' -ImapEnabled '${IMAP}"). Is it possible? Since this AFX Connector is using the PowerShell Server to translate from ssh to PowerShell on the Exchange Server, what are the limitations with the existing Microsoft Exchange Connectors? Any commands can be passed through Exchange Connector. The PowerShell Server is used to reach out to the endpoint, invoke the PowerShell, and execute the command. Explanation for the example: This command can be passed through any of the RSA Identity Governance and Lifecycle AFX Exchange Connector commands. What we have to do is, copy the command to Shell Command box and create parameters to pass values to the command being executed. The parameters have to be created for example, such as - Identity, ActiveSync, OWAEnabled, POP3, and IMAP and then pass the actual values for these parameters to the command while executing it. 4. What do I do if following error type is seen while executing any command using Microsoft Exchange Connector: java.io.ioexception: Session.connect: java.net.connectexception: Connection refused at net.sf.commons.ssh.jsch.jschconnectionfactory.connectusingpassword(jschconnectionfactory.java:8 2)... Caused by: com.jcraft.jsch.jschexception: Session.connect: java.net.connectexception: Connection refused at com.jcraft.jsch.session.connect(session.java:504) at net.sf.commons.ssh.jsch.jschconnectionfactory.connectusingpassword(jschconnectionfactory.java:7 2)... 56 more 2014-05-07 09:40:04.528 [WARN] com.aveksa.afx.transport.ssh.sshsettingstest:74 - Error connecting to SSH for endpoint test 45
java.io.ioexception: Session.connect: java.net.unknownhostexception: adiamgtw3.development.nyiso.com at net.sf.commons.ssh.jsch.jschconnectionfactory.connectusingpassword(jschconnectionfactory.java:8 2) 1. Please make sure that all of the installation steps mentioned in the Installation section of this guide in Configuring SSH PowerShell Server on windows for remote access are followed and Enable impersonation checkbox is unchecked/disabled in Other tab of the PowerShell Server window. 2. Also, make sure that from Microsoft Exchange Connector Settings page, provided Login Name is same with the administrator user by which PowerShell Server is being run. 46
Active Directory Connector Dependent Microsoft Exchange Connector Configure a Microsoft Exchange Connector with an Active Directory Connector to create a mailbox in Microsoft Exchange for an account being created in an Active Directory. Steps to configure: 1. Create a Microsoft Exchange Connector in an Active State. 2. Create an Active Directory Connector in a Test State. For more information about Active Directory connector, please see RSA_Via_L-G_Active_Directory_Appguide 3. On the Settings page of the Active Directory Connector, in the Dependent Exchange Connector setting under Miscellaneous, select the Microsoft Exchange Connector created in step 1. 4. Click OK. Note: Microsoft Exchange does not allow special characters like @ in mailbox identity name; the connector will show an error. But if we run a CreateAccount command for Active Directory Connector which is configured with Microsoft Exchange Connector (i.e. dependent Exchange Connector), the connector shows successful status message because an account is created in Active Directory and not in Microsoft Exchange. Example: Configuring Active Directory Connector Dependent Microsoft Exchange 2010 Connector: a. Create a Microsoft Exchange Connector 2010 in Active state. b. Create an Active Directory Connector and then configure it with Microsoft Exchange 2010 Connector created in Step 1, as shown below. Save the Active Directory Connector. 47
48
COPYRIGHTS Copyright 2016 EMC Corporation. All Rights Reserved. Published in the USA. TRADEMARKS RSA, the RSA Logo, and EMC are either registered trademarks or trademarks of EMC Corporation in the United States and/or other countries. All other trademarks used herein are the property of their respective owners. For a list of EMC trademarks, go to www.rsa.com/legal/trademarks_list.pdf. 49