Using PowerShell to Manage Box.com - Part 2: Using PowerShell to register your Box app on your workstation

If you've gotten here before reading part 1 of this series you want to read that first.  I has some important information that will help make sense of what this post is about.

Now that we've registered our application with developers.box.com, we need to grant our Box account access to use it.  I created a function in PowerShell that will bring you to the Box app site (which allows you to grant permission) and then grabs the information returned by Box and write it to your workstation's registry.

Just a little back ground (for a complete understanding read Box's official OAuth 2.0 document).

Basic layman's terms
In order to use the app you registered with Box, Box's OAuth2 implementation requires that you grant your Box account access to the application.  The granting process is an interactive process within your browser.  So you can't just write a script to carry out the granting process.  Once you've granted permission to the app, Box will redirect your browser (remember the redirect_uri) to a site you configured in the app.  The address bar contains the URI specified by the redirect_uri and appends a security token (which will be arbitrarily set during the registration process) and the initial authorization code.

The initial authorization code has a very short life.  It will expire within 30 seconds.  So if you don't use it to to retrieve your access token in time, you will have to go through the granting process again.
NOTE:  You can go through the granting process as many times as you like.  My PowerShell function actually makes it a rather painless process.

Once you get your authorization code you will need to leverage Box's RESTful API (within 30 seconds) to obtain an access token.  The API returns 5 attributes that my PowerShell function writes to your workstation's registry.

• access_token #This is the actual token needed to issue commands against Box's APIs
• expires_in #This is the life of the token (always roughly 1 hour give or take a few minutes)
• restricted_to #This always comes back blank for me and I haven't had a need for this attribute
• refresh_token #After the one hour expiration of your access token you will need to use this token to get a new access token.  All of my functions first check to see if the current access token is expired, if so it will refresh automatically.
• token_type #I'm not sure of all the types, but we will be dealing with the 'bearer' type.

So let's take a look at the actual PowerShell function that does all of that:

[edit]

NOTE:  I make calls to Test-RegKey, Set-RegKey, Set-RegValue.  These are not cmdlets that are built into PowerShell.  Instead, they are part of a suite of registry function that I created during one of the Scripting Games I participated in a few years ago.  I keep them in a separate module which you can download here.

I re-wrote the function to use PowerShell's native ability to access the registry (new-item, set-itemproperty, get-itemproperty, test-path).  You no longer need to import the RegEditSuit.psm1 module.

Here is the function:

Let's break the function down:
First the parameters:

• $AppName 
• This is actually an arbitrary name you give for registration purposes.  I used the same name I provided when I registered my application on Box.com.  While it arbitrary, remember that a registry key will be created for this app and that the Box function I create reference the registry key that gets created.  So you will want to remember the name you give it.
• $ClientID
• You recorded this string when you registered the application on Box.com.  You will need to provide that string.
• $ClientSecret
• You recorded this string when you registered the application on Box.com.  You will need to provide that string.
• $APIKey
• This is actually the $ClientID.  I personally like to record it into my workstation registry as APIKey, but it is not required to use any of the Box functions I created.
• $SecurityKey
• This is an arbitrary string.  The function has a default one.  The official Box documentation recommends that you use an anti-forgery state token to prevent CSRF attacks to your users.  But I believe that is for mobile apps you will publishing to their app store.  I don't think that forgery is an issues for colleagues that may be using your PowerShell scripts (imo).

So the first thing the script does it to make sure that a registry key exists under HKLM\software\box.com\.  If it doesn't exist then it creates it.

You can register multiple apps.

It then records the Client_ID, Client_Secret, and the APIKey at the root of that registry key.

It next runs through the interactive granting authorization process to retrieve the authentication code.  It starts by opening IE and navigating to a URI that includes the Client_ID and the arbitrary security key.  Then pops up a msgbox with instructions to finish the interactive authorization in IE before clicking OK. 

Let's take a look at what that process like in IE.

IE Opens to an Authentication Page

Once Authorized Grant or Deny Access

The site I land on I created additional instructions.  The green box shows the arbitrary security key for validation and the red box shows the authorization code.

Back in PowerShell click the OK button and PowerShell will grab the authorization code out of the LocationURL value.

Back to 'Register-BoxApp' function:

Once you click OK the function next loads up a hashtable with the AuthCode, clientID, clientSecret, it sets the RESTful URI and then invokes the RestMethod.

Here is the outcome in PowerShell of waiting too long (more that 30 seconds) to click the OK button.

Here is the outcome in PowerShell if you successfully click the OK button with 30 seconds.

If you wait too long to click OK this is the error you get.  Code is good for 30 seconds.

Results for successfully clicking OK within 30 seconds.

You may notice that after the Invoke-RestMethod line in the Register-BoxApp function, if there is a Access Token, the script will run the 'Register-BoxAccessToken'.  Here is what that function looks like:
[Edit]
Note:  I re-wrote the function to use PowerShell's native ability to access the registry (new-item, set-itemproperty, get-itemproperty, test-path).

Because the return data type of Invoke-RestMethod to Box is JSON, Invoke-RestMethod returns a PSCustomObject.  That means I have to provide the property names of the object ($RegValueNames) - unlike a hashtable where I could request the keys and interate through the key names to accomplish the same thing the function does with the PSCustomObject.

You will notice in the 'Register-BoxAccessToken' function as I'm iterating through the valuenames I check to see if the value name equals 'expires_in'.  That is because the data returned from Box is the number of seconds the access code is good before it expires.  So I create a datetime object and add the seconds to it and convert it to a string to store in the registry.  In a later post you will see how a function called 'Get-BoxAccessToken' exploits that datetime object in order to determine if the token needs to be refreshed.

If all goes well then AccessTokenInfo is written to your workstation's registry.

BoxAccessToken is a sub key and the access token, expires_in, and refresh token are registered here.

In the next post, I will discuss the functions 'Get-BoxAccessToken' and 'Refresh-BoxAccessToken, which are incorporated in all the work functions you will create in the future.

I've uploaded the entire OAuth2 PowerShell module for you to grab here.

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.