Our firm has built some customized Captive Web Portals for customer’s guest networks over the years. Many of this times the customers have been asking for a customized front end for creating the guest accounts.
Since Aerohive ID Manager has a API, I thought I would check it out.
Unfortunately the official documentation isn’t very well written and contains some error.
You will find it here API documentation

Setting up the API

First step is to activate API in ID Manager

Activate-API
Next step is to test the API with a REST client.
I started with a browser plugin called Postman for Chrome
You will find it here (Postman)

There are some different APIs called by different URLs depending on function.
To start with a query to get some information from ID-Manager, I started with a question on available guest types.
To do this you should do a POST to the URL: https://idmanager.aerohive.com/idmanager/API/external/queryguesttypes

Postman
Leave Authorization to No Auth. You will authorize yourself with the Token generated in ID-Manager in the Body later.
You have to present the request as a json in your Header.
Postman-header
Then in the Body you will start with the generated Token in ID Manager to authorize your request.
The queryguesttype API takes to values. Your token and Policy
Postman-body

The response should be a http200 looking like this:

{"errorCode":200,"errorMessage":null,"guestTypes":["Contractor","Vendor","Visitor","testtype"]}

In the array ”guestTypes” you should see your guest types in ID-Manager
GuestTypes

After some test I noticed that If you have a guest type with self-registration activated, this type can’t be used with the API and therefor you shouldn’t get it in the response when query with the API.

Another thing I noticed was if you do any typos in your Body, or if you send a variable or value ID-Manager don’t expect you get a login page in return
html-login-return

Communicating with the API

Okay, now we know that our Token is working and we have communication via the API.
Let’s try to create an account

First we have to create a guest type.
In the guest type we set the rules for the account. To which SSID the account is tied to and for how long it will be active and when the timer starts counting down. Either from account creation or when the accounts logs on for the first time.

CreateGuestTypes

After you created your guest type in ID-manager we try to query the createcredential API with token, policy, deliverMethod, phone or email and guestType in you Body

{
"token": "ewogICJpc3N1ZXIiIDogIkFlcm9oaX{...}ZlIElEITHFmTFRJeHlIekVsQT09Igp9",
"policy": "Guest-Access",
"deliverMethod":2,
"phone": "+46xxxxxxxx",
"guestType": "testtype"
}

Depending on delivery method (email = 1, sms = 2, both = 3) you have to have either phone or email as input. This will be the username for the account.
The password will be randomly generated.

deliverMethod:0 wont work.

If you called the API correctly you should get a response like this:

CreateAPIReply

Take a look inside ID-manager and see if there are an account

IDmanagerCreatedAccount

The next step is to move the API call from Postman to a web-server so we could start to build a front-end.
So far I have just made some sample code in PHP for testing.



<?php
//API Url
$url = 'https://idmanager.aerohive.com/idmanager/API/external/createcredential';
$data = array(
'token' => 'ewogICJpc3N1ZXIiIDogIkFlcm9oaXZlIElEIE1hb{...}vUEpVoQ05MMExGTHFmTFRJeHlIekVsQT09Igp9',
'deliverMethod' => '2',
'policy' => 'Guest-Access',
'email' => '[email protected]',
'guestType' => 'testtype',
'phone' => 'not used'
);
$data_string = json_encode($data);
$result = file_get_contents($url, null, stream_context_create(array(
'http' => array(
'method' => 'POST',
'header' => 'Content-Type: application/json' . "\r\n"
. 'Accept: application/json' . "\r\n",
'content' => $data_string,
),
)));
print_r($result);
?>

 

If you put your code on a Microsoft IIS web server you could easily manage access to the webpage with the built in authentication.

Conclusions

I think it’s good that there is an API which gives you the opportunity to customize your own GUI.
Unfortunately the documentation isn’t the best and I miss some features.
For example to choose your own username or password for the accounts.
You could do a workaround by entering any username as email address since there is no validation on it. But then you have to implement your own way to deliver the credentials to the users.
This could be done by PHP plugins for email on your webserver hosting the front-end.
The password is always randomized and the complexity is set in the ID manager settings. Unfortunately this settings apply to all guest-types and has a minimum of 8 characters since it should work with a PPSK (Private Pre Shared Key).

Lämna en kommentar

E-postadressen publiceras inte. Obligatoriska fält är märkta *