This is Part 2 of a series dedicated to Isilon and Powershell. In Part 1 we looked at the basics of how to leverage Powershell for REST scripting and ended with a quick example with parts from Jeremy. In this part we will have a more detailed view on the two authentication methods for REST offered by Isilon.

HTTP Basic Authentication:

The first way of authenticating the REST call is to send a HTTP basic authentication header with every call. This is simple as you just combine your username + password and encode the string with Base64. In Part 1 I already posted an example for basic authentication and will now explain it in more detail.

The first part is to create the basic authorization header encoded with Base64. (username and password would be passed as a parameter in a cmdlet later)

# create header
$username = "root"
$password = "a"
$EncodedAuthorization = [System.Text.Encoding]::UTF8.GetBytes($username + ':' + $password)
$EncodedPassword = [System.Convert]::ToBase64String($EncodedAuthorization)
$headers = @{"Authorization"="Basic $($EncodedPassword)"}

The next part is to create the uri (unified resource identifier). In the Isilon Platform API documentation you can find the different resource URLs available. In this case we are going to send a call to the SMB shares resource.

# create Uri for SMB shares
$isilonip = "10.0.0.1"
$baseurl = 'https://' + $isilonip +":8080" 
$resourceurl = "/platform/1/protocols/smb/shares"
$uri = $baseurl + $resourceurl

In the last part we are creating a REST call with the “Invoke-RestMethod” of powershell to get (Method: GET) all available SMB shares. With the switch “headers” we send our created authorization header.
The “ISIObject” is a powershell object which holds all the SMB shares and its configuration parameters. This object can be used e.g. as an input to a second cmdlet.

# send request to get all shares
$ISIObject = Invoke-RestMethod -Uri $uri -Method GET  -Headers $headers

This was easy. But what is the downside? Isilon needs resources to decode the authentication header of every call. Furthermore you have to store the encoded header securely somewhere if you want to do multiple calls without entering the password again and again. If someone gets access to the string he will be able to authenticate now and in the future to the Isilon! This could be a security issue.

Session cookies:

The solution is to leverage session cookies. In this way we first use a REST call to authenticate with Isilon and receive a session cookie. In successive calls we just pass the cookie along with our REST calls. The advantage is that Isilon just needs to authenticate you once. Furthermore the session does have a limited idle and life time which increases security.

# input variables
$username = "root"
$password = "a"
$isilonip = "10.0.0.1"
$baseurl = "https://" + $isilonip + ":8080"

If you enter a FQDN of a SmartConnect zone rather than a node or SmartConnect Service IP you will have to resolve the IP of the FQDN first. This is necessary as you are only able to use the session cookie with the same node where you have done the authentication. This can be done by:

# resolve FQDN
$isilonip = ([System.Net.Dns]::GetHostAddresses($isilonip)).IPAddressToString

The username and password are sent to the Isilon in the body of the REST call as a JSON object. Encryption is done by SSL. You can also decide if you want to get a session cookie for the “platform API”, the “namespace” or both. In our example we request a session for both.

#create Jason Object
$jobj = convertto-json (New-Object PSObject -Property @{username= $username;password = $password; services = ("platform","namespace")})

The next step is to create the URI for the session resource.

# create uri for session resource url
$resourceurl = "/session/1/session "
$uri = $baseurl + $resourceurl

Next we send our REST call with the credentials in the body. If we do a “post” we have to specify the contentype, which is “application/json”. We also have to specify the session variable where we will save the cookie. Please note that you only specify the name of the variable and not the variable itself. (in our case “session” instead of “$session”)

#create session and save cookie in variable $session
$ISIObject = Invoke-RestMethod -Uri  $uri -Body $jobj -ContentType "application/json; charset=utf-8" -Method POST -SessionVariable session

Finally we use our session cookie to authenticate our REST call to receive all SMB shares. The cookie is passed by using the parameter “WebSession” and our session variable

# create Uri for SMB shares
$resourceurl = "/platform/1/protocols/smb/shares"
$uri = $baseurl + $resourceurl

# send request to get all shares using session cookie
$ISIObject = Invoke-RestMethod -Uri $url -Method $method -WebSession $session

Conclusion:

Personally I think that using session authentication is the way to go. With powershell it is very simple to leverage this authentication method and you can write secure and rich powershell cmdlets.

In Part 3 I will introduce a couple of cmdlets which cover session handling. These cmdlets should help you to start writing your own scripts or cmdlets.