Microsoft Powershell Active Directory
78 min
this connector leverages microsoft powershell active directory cmdlets to manage email rules, compliance, and security features within an organization's active directory microsoft powershell active directory is a powerful tool for managing and automating tasks within active directory environments this connector enables swimlane turbine users to streamline active directory management, compliance searches, and email security operations directly from the swimlane platform by integrating with microsoft powershell active directory, users can automate actions such as managing quarantine messages, compliance searches, transport rules, and tenant allow/block list items, enhancing the efficiency and responsiveness of security workflows prerequisites to utilize the microsoft powershell active directory connector for turbine, ensure you have the following prerequisites custom authentication with the following parameters username the account username with permissions to execute active directory cmdlets password the corresponding password for the provided username modern authentication with the following parameters certificate the file path to the certificate used for secure authentication certificate password the password to access the certificate file app id the application identifier registered in azure ad for delegated permissions organization the name of the organization or tenant in which the operations will be performed capabilities this connector provides the following capabilities delete quarantine message get compliance search action get compliance search get hosted content filter policy get messagetrace get quarantine message get quarantine message header get tenant allow block list items get transport rule new compliance search new compliance search action new tenant allow/block list items new transport rule release quarantine message remove compliance search and so on configurations powershell basic auth authenticates to exchange online with username and password configuration parameters parameter description type required placeholder placeholder that will be removed string optional un username string required password password string required error status code the status codes more than 300 can also be used boolean optional powershell modern authentication authenticates using certificate file path, password, app id and organization name configuration parameters parameter description type required base64 encoded cert base64 encoded client side certificate string required cert password this is the password which was given while generating the certificate string required app id application id string required error status code the status codes more than 300 can also be used boolean optional org name of the organization string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions delete quarantine message remove a specified quarantine message from your organization with microsoft powershell's delete quarantinemessage cmdlet endpoint url / method get input argument name type required description identity string optional unique identifier identities array optional unique identifier whatif boolean optional parameter for delete quarantine message entitytype string optional type of the resource harddelete boolean optional parameter for delete quarantine message recipientaddress array optional parameter for delete quarantine message output parameter type description output object output field output delete quarantine message string response message status code number http status code of the response headers object http headers for the request reason string response reason phrase example \[ { "output" { "delete quarantine message" "quarantine message 1c742508 01be 4dab 557f 08dc0cd56816\\\66270fb6 5579 7394 6699 " }, "status code" 200, "headers" null, "reason" "ok" } ] get compliance search retrieve estimated compliance search results from exchange server 2016 or later and the microsoft purview compliance portal endpoint method get input argument name type required description case string optional the case parameter filters the results by the name of an ediscovery standard case that the compliance search is associated with if the value contains spaces, enclose the value in quotation marks domaincontroller string optional the domaincontroller parameter specifies the domain controller that's used by this cmdlet to read data from or write data to active directory you identify the domain controller by its fully qualified domain name (fqdn) identity string optional the identity parameter specifies the compliance search that you want to view resultsize number optional the resultsize parameter specifies the maximum number of results to return if you want to return all requests that match the query, use unlimited for the value of this parameter get compliance search action retrieve compliance search actions from microsoft exchange using the get compliancesearchaction cmdlet endpoint method get input argument name type required description case string optional the case parameter filters the results by the name of an ediscovery standard case that the compliance search is associated with if the value contains spaces, enclose the value in quotation marks domaincontroller string optional the domaincontroller parameter specifies the domain controller that's used by this cmdlet to read data from or write data to active directory you identify the domain controller by its fully qualified domain name (fqdn) identity string optional the identity parameter specifies the compliance search that you want to view details boolean optional the details parameter specifics if verbose details should be returned resultsize number optional the resultsize parameter specifies the maximum number of results to return if you want to return all requests that match the query, use unlimited for the value of this parameter get hosted content filter policy retrieve the configuration of spam filter policies within your organization using microsoft powershell active directory endpoint method get input argument name type required description identity string optional the identity parameter specifies the spam filter policy that you want to view you can use any value that uniquely identifies the policy for example name, distinguished name (dn), guid get message trace trace email messages through the organization using microsoft powershell's get messagetrace cmdlet input argument name type required description args string optional parameter for get message trace output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "thu, 2 may 2024 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] get quarantine message retrieve quarantined messages and files from sharepoint, onedrive, and microsoft teams for review endpoint url / method get input argument name type required description args string optional parameter for get quarantine message output parameter type description output array output field output identity string unique identifier receivedtime string time value organization string output field organization messageid string unique identifier senderaddress string output field senderaddress recipientaddress array output field recipientaddress subject string output field subject size number output field size type string type of the resource policytype string type of the resource policyname string name of the resource tagname string name of the resource permissiontoblocksender boolean output field permissiontoblocksender permissiontodelete boolean output field permissiontodelete permissiontopreview boolean output field permissiontopreview permissiontorelease boolean output field permissiontorelease permissiontorequestrelease boolean output field permissiontorequestrelease permissiontoviewheader boolean output field permissiontoviewheader permissiontodownload boolean output field permissiontodownload released boolean output field released releasestatus string status value systemreleased boolean output field systemreleased recipientcount number count value quarantinetypes string type of the resource example \[ { "output" \[ {} ], "status code" 200, "headers" null, "reason" "ok" } ] get quarantine message header retrieve the message header of a quarantined email using the 'identity' parameter in microsoft powershell active directory endpoint url / method get input argument name type required description identity string required unique identifier entitytype string optional type of the resource recipientaddress array optional parameter for get quarantine message header output parameter type description output object output field output identity string unique identifier organization string output field organization header string output field header status code number http status code of the response headers object http headers for the request reason string response reason phrase example \[ { "output" { "identity" "9a3a0d26 9776 4f99 c803 08dc1049994d\\\9041764c 9101 2ca9 48b8 39dd693460c0", "organization" "f5d73c4c bb3d 421b 8bee 424916a4acca", "header" "authentication results dkim=none (message not signed)\r\n header d=none;dmarc=non " }, "status code" 200, "headers" null, "reason" "ok" } ] get tenant allow block list items retrieve entries from the tenant allow/block list in microsoft defender by specifying the listtype endpoint method get input argument name type required description entry string optional the entry parameter filters the results based on the listtype parameter value valid values are filehash the exact sha256 file hash value sender the exact domain or email address value url the exact url value ip ipv6 addresses only single ipv6 addresses in colon hexadecimal or zero compression format or cidr ipv6 ranges from 1 to 128 this value is shown in the value property of the entry in the output of the get tenantallowblocklistitems cmdlet listtype string required the listtype parameter specifies the list to view allow boolean optional the allow switch filters the results for allow entries you don't need to specify a value with this switch block boolean optional the block switch filters the results for block entries you don't need to specify a value with this switch expirationdate string optional the expirationdate parameter filters the results by expiration date in coordinated universal time (utc) to specify a date/time value for this parameter, use either of the following options specify the date/time value in utc for example, "2021 05 06 14 30 00z " specify the date/time value as a formula that converts the date/time in your local time zone to utc for example, (get date "5/6/2020 9 30 am") touniversaltime() for more information, see readme listsubtype array optional the listsubtype parameter filters the results by subtype valid values are advanceddelivery tenant (default value) noexpiration boolean optional the noexpiration switch filters the results by entries that are set to never expire you don't need to specify a value with this switch outputjson boolean optional the outputjson switch specifies whether to return all entries in a single json value you don't need to specify a value with this switch use this switch to prevent the command from halting on the first entry that contains a syntax error get transport rule retrieve a list of email transport rules from your organization's system using microsoft powershell active directory endpoint url / method get input argument name type required description args string optional a string including valid keyworkd arguments for this command for a list of valid arguments, please see https //learn microsoft com/en us/powershell/module/exchange/get transportrule?view=exchange ps#syntax https //learn microsoft com/en us/powershell/module/exchange/get transportrule?view=exchange ps#syntax output parameter type description output object output field output priority number output field priority dlppolicy object output field dlppolicy dlppolicyid string unique identifier comments string output field comments createdby string output field createdby lastmodifiedby string output field lastmodifiedby manuallymodified boolean output field manuallymodified activationdate object date value expirydate object date value description string output field description ruleversion object output field ruleversion major number output field major minor number output field minor build number output field build revision number output field revision majorrevision number output field majorrevision minorrevision number output field minorrevision size number output field size conditions object output field conditions exceptions object output field exceptions actions array output field actions state string output field state mode string output field mode ruleerroraction string error message if any example \[ { "output" { "priority" 0, "dlppolicy" null, "dlppolicyid" "00000000 0000 0000 0000 000000000000", "comments" "\n", "createdby" "travis riley", "lastmodifiedby" "travis riley", "manuallymodified" false, "activationdate" null, "expirydate" null, "description" "take the following actions \r\n\tset message header 'x vmray auth' with the value ' ", "ruleversion" {}, "size" 397, "conditions" null, "exceptions" null, "actions" \[] }, "status code" 200, "headers" \[], "reason" "ok" } ] new compliance search initiates a new compliance search in exchange server 2016 or later and microsoft purview using the new compliancesearch cmdlet input argument name type required description name string optional name of the resource exchangelocation string optional parameter for new compliance search allownotfoundexchangelocationsenabled number optional parameter for new compliance search contentmatchquery string optional response content confirm boolean optional parameter for new compliance search exchangelocationexclusion string optional parameter for new compliance search description string optional parameter for new compliance search holdnames string optional name of the resource includeorgcontent number optional response content includeuserappcontent number optional response content language string optional parameter for new compliance search loglevel string optional parameter for new compliance search publicfolderlocation string optional parameter for new compliance search refinernames string optional name of the resource sharepointlocation string optional parameter for new compliance search sharepointlocationexclusion string optional parameter for new compliance search statusmailrecipients string optional status value whatif boolean optional parameter for new compliance search output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "thu, 2 may 2024 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] new compliance search action initiates a new content search in exchange server and microsoft purview compliance portal using the new compliancesearchaction cmdlet input argument name type required description searchname string optional name of the resource purge boolean optional parameter for new compliance search action purgetype string optional type of the resource actionname string optional name of the resource archiveformat string optional parameter for new compliance search action enablededupe string optional parameter for new compliance search action exchangearchiveformat string optional parameter for new compliance search action export boolean optional parameter for new compliance search action filetypeexclusionsforunindexeditems string optional type of the resource force boolean optional parameter for new compliance search action format string optional parameter for new compliance search action includecredential boolean optional parameter for new compliance search action includesharepointdocumentversions boolean optional parameter for new compliance search action joboptions string optional parameter for new compliance search action notifyemail string optional parameter for new compliance search action notifyemailcc string optional parameter for new compliance search action preview boolean optional parameter for new compliance search action referenceactionname string optional name of the resource region string optional parameter for new compliance search action report boolean optional parameter for new compliance search action retentionreport boolean optional parameter for new compliance search action retryonerror boolean optional error message if any scenario string optional parameter for new compliance search action scope string optional parameter for new compliance search action searchnames string optional name of the resource output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "thu, 2 may 2024 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] new tenant allow/block list items create new entries in the tenant's allow/block list with microsoft powershell, specifying list types and expiration options endpoint url / method get input argument name type required description entries array optional the entries parameter specifies the values that you want to add to the tenant allow/block list based on the listtype parameter value listtype string optional the listtype parameter specifies the type of entry to add allow boolean optional the allow switch specifies that you're creating an allow entry block boolean optional the allow switch specifies that you're creating a block entry expirationdate string optional the expirationdate parameter set the expiration date of the entry in coordinated universal time (utc) listsubtype string optional the listsubtype parameter specifies the subtype for this entry noexpiration boolean optional the noexpiration switch specifies that the entry should never expire you don't need to specify a value with this switch logextradetails boolean optional the log extra details parameter notes string optional the notes parameters specifies additional information about the object removeafter number optional the removeafter parameter enables the remove on > 45 days after last used date feature for an allow entry submissionid string optional this parameter is reserved for internal microsoft use new transport rule creates a new transport rule in microsoft powershell active directory to manage mail flow using the provided name endpoint url / method get input argument name type required description name string required display name for the rule being created betweenmemberof1 string optional the betweenmemberof1 parameter specifies a condition that looks for messages that are sent between group members you need to use this parameter with the betweenmemberof2 parameter betweenmemberof2 string optional the betweenmemberof2 parameter specifies a condition that looks for messages that are sent between group members you need to use this parameter with the betweenmemberof1 parameter deletemessage boolean optional action to delete the message matching this rule redirectmessageto string optional the redirectmessageto parameter specifies a rule action that redirects messages to the specified recipients stopruleprocessing boolean optional the stopruleprocessing parameter specifies an action that stops processing more rules prependsubject string optional the prependsubject parameter specifies an action that adds text to add to the beginning of the subject field of messages rejectmessagereasontext string optional the rejectmessagereasontext parameter specifies the explanation text that's used when the rule rejects messages output parameter type description output object output field output priority number output field priority dlppolicy object output field dlppolicy dlppolicyid string unique identifier comments object output field comments createdby string output field createdby lastmodifiedby string output field lastmodifiedby manuallymodified boolean output field manuallymodified activationdate object date value expirydate object date value description string output field description ruleversion object output field ruleversion major number output field major minor number output field minor build number output field build revision number output field revision majorrevision number output field majorrevision minorrevision number output field minorrevision size number output field size conditions array output field conditions exceptions object output field exceptions actions array output field actions state string output field state mode string output field mode ruleerroraction string error message if any example \[ { "output" { "priority" 13, "dlppolicy" null, "dlppolicyid" "00000000 0000 0000 0000 000000000000", "comments" null, "createdby" "integrations", "lastmodifiedby" "integrations", "manuallymodified" false, "activationdate" null, "expirydate" null, "description" "if the message \r\n\tbetween members of the groups 'luis xvi\@swimlane com' and 'mar ", "ruleversion" {}, "size" 522, "conditions" \[], "exceptions" null, "actions" \[] }, "status code" 200, "headers" \[], "reason" "ok" } ] release quarantine message facilitates the release of specified messages from quarantine to recipients in a cloud based organization via microsoft's release quarantinemessage cmdlet endpoint url / method get input argument name type required description user array optional parameter for release quarantine message identity string optional unique identifier allowsender boolean optional parameter for release quarantine message force boolean optional parameter for release quarantine message releasetoall boolean optional parameter for release quarantine message reportfalsepositive boolean optional parameter for release quarantine message whatif boolean optional parameter for release quarantine message output parameter type description output object output field output status code number http status code of the response headers object http headers for the request reason string response reason phrase example \[ { "output" {}, "status code" 200, "headers" null, "reason" "ok" } ] remove compliance search removes existing compliance searches from exchange server 2016 and the microsoft purview compliance portal endpoint method get input argument name type required description confirm boolean optional the confirm switch specifies whether to show or hide the confirmation prompt how this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding identity string optional the identity parameter specifies the compliance search that you want to remove whatif boolean optional the whatif switch simulates the actions of the command you can use this switch to view the changes that would occur without actually applying those changes remove tenant allow block list items removes specified entries from the microsoft defender tenant allow/block list using provided list types endpoint method get input argument name type required description ids array optional the ids parameter specifies the entries that you want to remove this value is shown in the identity property in the output of the get tenantallowblocklistitems cmdlet an example value for this parameter is rgaaaaai8gsyi nmqqzeh hxjbywbwcqfqnjy8hbtbdlkfkv6bcuaaal qczaacqfqnjy8hbtbdlkfkv6bcuaaal ospaaaa0 you can't use this parameter with the entries parameter entries array optional the entries parameter specifies the entries that you want to remove based on the listtype parameter value valid values are filehash the exact sha256 file hash value sender domains and email addresses the exact domain or email address value url the exact url value ip ipv6 addresses only single ipv6 addresses in colon hexadecimal or zero compression format or cidr ipv6 ranges from 1 to 128 this value is shown in the value property of the entry in the output of the get tenantallowblocklistitems cmdlet you can't mix value types (sender, url, file, or ip address) or allow and block actions in the same command you can't use this parameter with the ids parameter listtype string required the listtype parameter specifies the type of entry that you want to remove valid values are filehash, sender, url, ip listsubtype string optional the listsubtype specifies further specifies the type of entry that you want to remove valid values are advanceddelivery use this value for phishing simulation urls tenant this is the default value outputjson boolean optional the outputjson switch specifies whether to return all entries in a single json value you don't need to specify a value with this switch you use this switch to prevent the command from halting on the first entry that contains a syntax error remove transport rule eliminate a specific transport rule in microsoft powershell active directory using the 'identity' parameter endpoint url / method get input argument name type required description identity string required the identity parameter specifies the rule that you want to remove you can use any value that uniquely identifies the rule whatif boolean optional the whatif switch simulates the actions of the command you can use this switch to view the changes that would occur without actually applying those changes output parameter type description output object output field output remove transport rule string output field remove transport rule status code number http status code of the response headers array http headers for the request file name string name of the resource file string output field file reason string response reason phrase example \[ { "output" { "remove transport rule" "rule hernan rule from manifest 1 removed" }, "status code" 200, "headers" \[], "reason" "ok" } ] set hosted connection filter policy modifies connection filter policies in a cloud based organization using microsoft powershell active directory cmdlets input argument name type required description identity string optional unique identifier admindisplayname string optional name of the resource configurationxmlraw string optional parameter for set hosted connection filter policy enablesafelist boolean optional parameter for set hosted connection filter policy ipallowlist string optional parameter for set hosted connection filter policy ipblocklist string optional parameter for set hosted connection filter policy makedefault string optional parameter for set hosted connection filter policy whatif boolean optional parameter for set hosted connection filter policy output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "thu, 2 may 2024 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] set hosted content filter policy modify spam filter policies in your cloud based organization using the set hostedcontentfilterpolicy cmdlet input argument name type required description addxheadervalue string optional value for the parameter admindisplayname string optional name of the resource allowedsenderdomains string optional parameter for set hosted content filter policy allowedsenders string optional parameter for set hosted content filter policy blockedsenderdomains string optional parameter for set hosted content filter policy blockedsenders string optional parameter for set hosted content filter policy bulkquarantinetag string optional parameter for set hosted content filter policy bulkspamaction string optional parameter for set hosted content filter policy bulkthreshold number optional parameter for set hosted content filter policy downloadlink boolean optional parameter for set hosted content filter policy enableenduserspamnotifications boolean optional parameter for set hosted content filter policy enablelanguageblocklist boolean optional parameter for set hosted content filter policy enableregionblocklist boolean optional parameter for set hosted content filter policy enduserspamnotificationcustomfromaddress string optional parameter for set hosted content filter policy enduserspamnotificationcustomfromname string optional name of the resource enduserspamnotificationcustomsubject string optional parameter for set hosted content filter policy enduserspamnotificationfrequency number optional parameter for set hosted content filter policy enduserspamnotificationlanguage string optional parameter for set hosted content filter policy enduserspamnotificationlimit number optional parameter for set hosted content filter policy highconfidencephishaction string optional unique identifier highconfidencephishquarantinetag string optional unique identifier highconfidencespamaction string optional unique identifier highconfidencespamquarantinetag string optional unique identifier identity string optional unique identifier increasescorewithbizorinfourls string optional url endpoint for the request output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "thu, 2 may 2024 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] set tenant allow/block list items updates the microsoft powershell active directory tenant allow/block list with specified json entries endpoint url / method get input argument name type required description ids array optional specifies the entries that you want to modify entries array optional the entries parameter specifies the entries that you want to modify based on the listtype parameter value listtype string optional specifies the type of entry that you want to modify valid values are "filehash", "sender", "url" allow boolean optional the allow switch specifies that you're modifying an allow entry you don't need to specify a value with this switch block boolean optional the block switch specifies that you're modifying a block entry you don't need to specify a value with this switch expirationdate string optional the expirationdate parameter filters the results by expiration date in coordinated universal time (utc) listsubtype string optional the listsubtype parameter further specifies the entry that you want to modify valid values are "advanceddelivery", "tenant" noexpiration boolean optional the noexpiration switch specifies that the entry should never expire you don't need to specify a value with this switch notes string optional the notes parameters specifies additional information about the object set transport rule modifies an existing transport rule in microsoft powershell active directory using a specified identity endpoint url / method get input argument name type required description identity string required specifies the rule that you want to modify you can use any value that uniquely identifies the rule name string optional display name for the rule being created betweenmemberof1 string optional the betweenmemberof1 parameter specifies a condition that looks for messages that are sent between group members you need to use this parameter with the betweenmemberof2 parameter betweenmemberof2 string optional the betweenmemberof2 parameter specifies a condition that looks for messages that are sent between group members you need to use this parameter with the betweenmemberof1 parameter deletemessage boolean optional action to delete the message matching this rule redirectmessageto string optional the redirectmessageto parameter specifies a rule action that redirects messages to the specified recipients stopruleprocessing boolean optional the stopruleprocessing parameter specifies an action that stops processing more rules prependsubject string optional the prependsubject parameter specifies an action that adds text to add to the beginning of the subject field of messages rejectmessagereasontext string optional the rejectmessagereasontext parameter specifies the explanation text that's used when the rule rejects messages start adsyncsync cycle initiates an active directory synchronization cycle with custom arguments using microsoft powershell active directory endpoint url / method get input argument name type required description args string required parameter for start adsyncsync cycle start compliance search initiates a compliance search in microsoft powershell active directory using predefined criteria endpoint method get input argument name type required description confirm boolean optional the confirm switch specifies whether to show or hide the confirmation prompt how this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding force boolean optional the force switch hides warning or confirmation messages identity string optional the identity parameter specifies the compliance search that you want to start retryonerror string optional the retryonerror switch specifies whether to retry the search on any items that failed without re running the entire search all over again whatif boolean optional the whatif switch simulates the actions of the command you can use this switch to view the changes that would occur without actually applying those changes response headers header description example content length the length of the response body in bytes 140 content type the media type of the resource application/json date the date and time at which the message was originated thu, 2 may 2024 20 37 23 gmt notes you need to be assigned permissions before you can run this cmdlet to find the permissions required to run any cmdlet or parameter in your organization, see find the permissions required to run any exchange cmdlet https //learn microsoft com/en us/powershell/exchange/find exchange cmdlet permissions?view=exchange ps the identities parameter identifies quarantined messages for bulk operations you identify the messages by using the syntax value1,value2 valuen each value is a unique quarantined message identifier in the format guid1\guid2 (for example c14401cf aa9a 465b cfd5 08d0f0ca37c5\4c2ca98e 94ea db3a 7eb8 3b63657d4db7) you can find the identity value for a quarantined message by using the get quarantinemessage cmdlet when you use this parameter, the identity parameter is required, but the value is ignored for more details on the syntax and documentation, please refer to microsoft powershell documentation https //learn microsoft com/en us/powershell/module/exchange/delete quarantinemessage?view=exchange ps to set up a certificate for the app follow this link https //learn microsoft com/en us/powershell/exchange/app only auth powershell v2?view=exchange ps to generate base64 encoded certificate perform below steps in powershell window $cert bytearray = get content path \<path of pfx file> asbytestream raw $base 64 encode cert string = \[system convert] tobase64string($bytearray) $base 64 encode cert string once you have the encoded certificate pass the $base 64 encode cert string value in asset for more details on the date syntax and documentation, please refer to date https //learn microsoft com/en us/powershell/module/microsoft powershell utility/get date?view=powershell 7 5