Office 365 PowerShell queries via REST: Maximizing the Kloudless Pass-through API

In our previous post, we announced the availability of the Kloudless Pass-through API. The Pass-through API enables your application to make API requests directly to third-party services, while still using Kloudless’s unified APIs. In this blog post, we’ll discuss how to access the Office 365 PowerShell via the Kloudless REST API to perform administrative tasks in Office 365.

Building with our easy-to-use REST API offers many benefits. We handle the complexities of integrating with each service behind the scenes so you  don’t have to. This speeds up your integration time and decreases future maintenance. We’ve extended the same principle to our Pass-through API by introducing special capabilities such as enabling PowerShell queries for Office 365 admin accounts.

Office 365 PowerShell provides several remote management commands that can be used to administer your Office 365 tenant, similar to how you would via the Office 365 admin center web application. For example, a broad set of security and compliance features can be accessed via theSecurity & Compliance Center cmdlets by connecting to Office 365 using remote PowerShell. Normally, you would need access to a PowerShell prompt in order to access this functionality. The Kloudless REST API handles the heavy-lifting and enables you to access this functionality via our REST API.

Invoking Office 365 Security Center cmdlets via the Kloudless Pass-through API

To begin, connect a SharePoint Online admin account to your Kloudless application. The easiest way to do this is by logging into your Kloudless account and then navigating to the Interactive Docs. Click the “Add Account” button and then click on SharePoint Online under the “Admin accounts” section towards the bottom of the pop-up that opens.

idjg03n

Once you’ve connected your account, you will receive a Kloudless Account ID that can be used for API requests to the Kloudless API. You are now ready to make Pass-through API requests to this admin Office 365 account!

While SharePoint Online REST API requests can be performed without any additional configuration, the PowerShell queries described in this blog post are available in Kloudless Enterprise and also require special permission to access by Kloudless Enterprise developers. Please contact us at support@kloudless.com to learn how to enable this capability for your Kloudless Enterprise instances.

Request Format

The format of PowerShell pass-through API requests is as follows:

URL: https://api.kloudless.com/v1/accounts/{account_id}/raw
  • {account_id} is the Kloudless account ID of the SharePoint Online admin account connected.
Headers (described in the Pass-through API docs):
  • X-Kloudless-Raw-URI: http://powershell/ This special value indicates the request should be translated to a PowerShell query.
  • X-Kloudless-Raw-Method: POST
  • Authorization: Bearer {account_bearer_token} OR Authorization: APIKey {application_api_key} See our Authentication Docs for more information on authorizing API requests.
Body
JSON data in the format below:

    {
      "category": "o365-security",
      "command": {cmdlet_name},
      "options": {
        ... option name: value mappings if required ...
      }
    }
At the current time, only Office 365 Security and Compliance Center cmdlets ("category": "o365-security") and Exchange Online cmdlets ("category": "exchange") are available via the Kloudless API. If you would like access to other remote PowerShell cmdlets, please contact us at support@kloudless.com.

Examples of Requests

An example of a curl request with the format described above would be:

curl -H "Authorization: APIKey {api_key}" \
     -H "X-Kloudless-Raw-URI: http://powershell/ \
    https://api.kloudless.com/v1/accounts/{account_id}/raw \
    --data '{body}'

Please replace the {api_key}, {account_id} and {body} values with your API Key, connected account’s ID and JSON data for PowerShell respectively.

Here are some examples of Body data to use in {body} for specific cmdlets:

Get-ComplianceCase
Obtaining a list of compliance cases.

{
  "category": "o365-security",
  "command": "Get-ComplianceCase"
}
An example of a curl request for this would be:

curl -H "Authorization: APIKey 123ABC" \
     -H "X-Kloudless-Raw-URI: http://powershell/" \
     https://api.kloudless.com/v1/accounts/123/raw \
     --data '{"category": "o365-security", "command": "Get-ComplianceCase"}'
New-ComplianceCase
Create a new compliance case.

{
  "category": "o365-security",
  "command": "New-ComplianceCase",
  "options": {
    "Name": "test new case 2",
    "Description": "This case is created via curl"
  }
}
An example curl request would be identical to the one used for Get-ComplianceCase but with the new value above for --data instead.
New-CaseHoldPolicy
Create a new hold policy for a case.

{
  "category": "o365-security",
  "command": "New-CaseHoldPolicy",
  "options": {
    "Case": "3b4de8d5-13cb-4291-bdd0-b6e2bb82a08e",
    "Name": "New Hold",
    "SharePointLocation": "https://kloudless.sharepoint.com/test subsite/"
  }
}
where "3b4de8d5-13cb-4291-bdd0-b6e2bb82a08e" is the Identity GUID of the Case to add the legal hold policy to. This corresponds to the Locations section of a Hold when editing a Case’s Holds at https://protection.office.com/#/ediscovery.
New-CaseHoldRule
Create a rule to add to a hold policy.

{
  "category": "o365-security",
  "command": "New-CaseHoldRule",
  "options": {
    "Policy": "New Hold",
    "Name": "New Rule",
    "ContentMatchQuery": "SSN"
  }
}
where "New Hold" is the name of the hold I created previously. This corresponds to the Conditions section of a Hold.

Similarly, other policies such as retention policies can also be created, and existing objects can be deleted:

New-RetentionCompliancePolicy
Create a new preservation policy.

{
  "category": "o365-security",
  "command": "New-RetentionCompliancePolicy",
  "options": {
    "Name": "Test new policy",
    "SharePointLocation": "https://kloudless.sharepoint.com/"
  }
}
This creates a policy but has not yet created a rule to add to it, which can be done with .
Remove-ComplianceCase
Deleting a compliance case.

{
  "category": "o365-security",
  "command": "Remove-ComplianceCase",
  "options": {
    "Identity": "94b99324-5574-4220-b081-1b689cb386af",
    "Confirm:$false": null
  }
}
where "94b99324-5574-4220-b081-1b689cb386af" is the Identity GUID of the Case to remove.

Future capabilities of the Pass-through API

The Pass-through API provides provides a powerful new way to access third-party features via Kloudless as shown above. We’re excited to make this available to all developers on our platform and would love to hear any feedback or suggestions in our developer forum.

Announcing the Kloudless Pass-through API

We are excited to announce the general availability of the new Kloudless Pass-through API endpoint. The Pass-through API enables your application to access the full functionality of the third-party software service by performing API requests directly to the service. Kloudless continues to ensure any relevant authentication information like refreshed access tokens are included in the API request.

While Kloudless provides unified APIs, there may be times when your application needs to access unique functionality in a third-party service that is not available in Kloudless’s unified APIs. The Pass-through API solves this problem by enabling your application to send raw data to a third-party API’s endpoint and receive the raw response streamed directly from the service through Kloudless.

Check out our API docs for more information on how to use the Pass-through API.

Kloudless API v1 Launches Today

Last week, we launched our Universal CRM API. You can read more about the announcement here. The new API kicks off our broader product strategy to provide Universal APIs for many important areas of business.

As part of this product launch, we are also launching v1 of our API. Our goal with v1 is to establish a strong foundation for building future products and functionalities.

 

What’s new in v1

The migration to v1 introduces new capabilities and improvements to existing functionality.

Universal CRM API
Previously, the Universal CRM API was only available in Kloudless Enterprise. With v1, the CRM API is available to any developer that prefers to use our cloud version at kloudless.com. You can start integrating the CRM API for free here.

OAuth 2.0
We are introducing a standards-compliant OAuth 2.0 authentication mechanism to connect user accounts, which enables easy integration with other tools that support OAuth 2.0. Other benefits include:

  • Documented support for out-of-band, authorization code grant, and implicit grant OAuth 2.0 flows to support authentication in any environment.
  • More granular scopes to better control the services, APIs and types of accounts users can connect to your app.
  • Improved security with white-listed Redirect URIs, validated Client IDs/Secrets, and verified Bearer tokens.

Read more about Kloudless authentication here.

Other enhancements
As you read through our documentation, you will find small improvements to many endpoints. For example, we’ve updated our old permissions format to support groups and our old pagination format to be more flexible.

 

What this means for you

First, any new applications you develop should use API v1.

Second, there are backwards incompatible changes in the migration from v0 to v1. API v1 is built thoughtfully, and we try to limit the changes you need to your implementation to only the things we consider most important moving forward. You should update your app’s integration with Kloudless as soon as possible.

Here is a summary of the backwards-incompatible changes.

API-namespacing for endpoints
All endpoints specific to the Storage API have been namespaced under /storage/. Learn more

OAuth 2.0 Authentication
OAuth 2.0 authentication is now required. The previous authentication format is no longer supported. OAuth 2.0 Bearer tokens have replaced Account Keys. Learn more

Events
Deprecated event object attributes have been removed. Learn more

Pagination
next_page must be used to identify the next page value for pagination. Learn more

File Uploads
Files are uploaded as binary content rather than via multipart form POST requests. Learn more

Permissions
File/Folder permission updates take in a list of permission objects rather than a mapping of user emails to roles. Learn more

Users of the UI Tools do not need to make changes to use v1, although they would have to make changes to switch to OAuth if using the Authenticator JS library or if using Account Keys from the File Explorer.

None of your users need to re-authenticate when you switch your app to either OAuth 2.0 or the v1 API.

 

Deprecating v0 and the old auth mechanism

As of today, v0 of the API is deprecated. In order to provide you with the most up-to-date features and support a single, consistent API platform, we’ll be turning off API v0 on February  28, 2018.

Our previous authentication mechanism will be turned off in one year on August 31, 2017.

In our next update, we will provide a more detailed deprecation timeline.

We love building for the thousands of developers using our platform. If you have any questions or feedback, we’d love to hear from you in our developer forum.