Using PowerShell to Manage Box.com - Part 1: Prepping for OAuth2 Protocol.

Wow!!! It's been quite a long time since my last post.  Life is so busy.

Anyway, I struggled for some time with RESTful APIs and finally got my head around it when I had to create some functions for my logical access team to manage on-boarding new enterprise users into Box.com (Box).  So I thought I'd share three modules I created around the process.

Even if you don't use the modules, they do demonstrate how easy it is to use the 'Invoke-RestMethod'.  It will also show you how to implement OAuth2 against Box's implementation of the protocol (which may be helpful).

As the title indicates this series of posts will be specific to Box's APIs.  It doesn't mean you can't use the same principles with other RESTful APIs or other OAuth2 sites, but my experience is specific to Box and so the information will be specific to Box.  I will discuss:

• Registering an application with Box on their developer site.
• Granting users access to your Box application.
• Registering your Box app in your workstation registry.
• Understanding and using the OAuth2 access token, refresh token, and token expiration.
• How to exploit Box API and convert curl commands to PowerShell functions.
• Create PowerShell functions using 'Invoke-RestMethod' for various tasks.

**Disclaimer**

The 'Using PowerShell to Manage Box.com' series of posts are a compilation of information I successfully used in my environment.  I am in no way claiming that this is the recommended method or the only way of using PowerShell to manage Box.  This information is what I have actually successfully developed for my requirements.

Also I am making three modules available to download.  I use aliases; commenting and help are sparse or even non-existent in the modules; so if that bothers you, just don't use the modules instead of being critical about it.

The documentation around using PowerShell to exploit RESTful APIs on the Internet is sparse at best, and using PowerShell to manage Box almost non-existent.  So I'm providing this to hopefully help other PowerShellers if they need to implement automation, or functionality in a similar fashion around other RESTful APIs or even specifically around the Box APIs.

So let's get to it.

When you want to use PowerShell to manage Box you will need to register an application with  http://developers.box.com.  Imagine you want to create a mobile app to exploit Box.com (they have SDKs for node, python, ruby, php, and haskell), in this case we are using PowerShell and will be accessing our application via a PowerShell console instead of a mobile device.

Let's look at some screen shots of creating a Box application.  I will be showing screen shots via my personal account (not my enterprise account).  The enterprise interface with Box is only slightly different.  If you are doing this via an enterprise account you should still be able to follow the process.

On your first login or upon clicking the link 'Create a Box Application' the following page appears:

• If you are in an enterprise environment the 'Box Content' API will allow you to manage user accounts, create folders, manage permissions on folders, create 'Shared Links', etc...  
• The 'Box View' API, allows you to manage the actually data like file views, file conversions, etc...  My functions were built for my logical access team so will exclusive be using the 'Content' API.

You will want to give your application a name (I've called my 'PowerShell Demo') and choose the API you want the application to use and click 'Create Application'.

Now you will want to configure your application and record some important information that will be needed in order to allow other users (even yourself) to use your PowerShell application.

Fill in the General info as you wish, none of that section will actually have any affect on you PowerShell code.

The OAuth2 Parameters section is the most critical part of this step.

You will want to record your client_id and client_secret for future reference (just paste it Notepad or something like that).

redirect_uri
The redirect_uri was the most confusing portion to me (probably because I'm just stupid - cause it made total sense once I figured it out).  Anyway, you'll want to set this to any web server that will handle SSL.  In my case my team uses a utility server that had IIS installed on it already.  I just grabbed a cert from my AD forest CA for the URL that I wanted to use and threw it on that server.

The redirect_uri is a URI that will redirect your browser.  Box doesn't actually write to this URI.  Box actually appends the redirect_uri with your initial authorization code and an arbitrary token.

This was probably the most confusing part of the OAuth2 process.  I was under the impression that Box needed access to the site to be able to place a file or some data that would be interpreted in your browser when redirected.  I searched for free public sites with this type of access in order to set my redirect_uri; and I read dozens and dozens of documents with no success of understanding this (I know, I know -- I'm stupid, right?).

So just to reiterate:  The redirect_uri is not a site that Box needs to write to.  It is a landing site for your browser and Box appends the URI in your address bar in your browser with the needed authorization code and the arbitrary token you provided on making the request for the authorization code.

The PowerShell script I'm going to show you next will automagically grab this authorization code and register your app in your workstation registry.  I'll show you that shortly.

Back to the config page on developer.box.com
If you scroll to the bottom of the configuration page you will see a section 'Backend Parameters'.  You will notice that the 'API Key' is the same as the client_id.  I make this distinction because if you want help from Box with your app they will want your API Key and that is it.  My PowerShell function records the API Key in your workstation's registry even though none of my other functions will ever actually use it.

When I first built the function I thought it might be import to distinguish between client_id and 'API Key'.  It ended up being a mute issue and isn't really a necessary part of the registration process in the PowerShell script I'm about to show you.  I'm keeping my function the way it is just in case I ever have a need for the distinction, but you can remove it from the register function if you so chose (don't worry you'll understand once we go over the function).

Save your application.

Okay, we've registered our application with Box.com.  We are done prepping our Box application and can now use our OAuth2 protocol to get access tokens and use the API to automate Box functionality.

Part 2 of this series will show how to register the important client_id and client_secret on your workstation; how to retrieve your initial authorization code, access token, refresh token, and token expiration and write that information to your workstation's registry.  We will also see how to refresh your access token when it expires.  We will dive into how Box implemented the OAuth2 protocol and how PowerShell can exploit their implementation.