Authentication and authorisation

Organisation

The organisational entity structure of the BB authorisation model is as follows:

Publication
    User
        Role
            Permission(s)

The highest hierarchical level is “Publication”. The Publication context is automatically fetched using the HTTP HOST header. E.g.: When the url http://bb.vms.bluebillywig.lan/api/bbauth?action=checkSession is called, the publication context will be bb, or whatever publication that is configured to be related to this host header.

By default, a user has read/write rights for all content in the home publication, and other publications that have shared access enabled.

The uri /api/bbauth is the main interface to the Blue Billywig authentication and authorization classes. It has one major parameter: action

All valid actions usable by external systems are described in the next sections.

We recommend using our RPC to log in to the vms as this will simplify the login process. The RPC also has basic functionality to call the api. We have a PHP RPC which is documented here as well as a Java RPC which is documented here.

 

Login to the VMS platform

To login into the Blue Billywig VMS platform a couple of actions have to be taken.

First a random key needs to be retrieved.

Request
/api/getRandom

Result
The returned XML will contain a random-key.

Example
/api/getRandom

[xml]
<?xml version="1.0"?>    
<response code="200" error="false">ktxqwgcb9h</response>

Next the password needs to be calculated. The plaintext password first needs to be encoded with md5 encoding and after that with base64 encoding. After this action the retrieved random-key needs to be added as postfix of the just encoded password. And finally this whole password string needs to be md5 and base64 encoded for the second time.

Example
Below a password encoding example in PHP is shown.

[php]
$encodedPassword = base64_encode(md5(base64_encode(md5($myplaintextpassword)).$randomkey));

After the password is encoded the actual login action can be executed, using the get_user action.

Request
/api/bbauth?action=get_user

Attribute Type Description
Required parameters    
username string The username of a VMS user/account.
password string The encoded password.

Result
If the login was successful a XML message containing the user information will be returned. If it was unsuccessful a login failed message will be returned.

Example
/api/bbauth?action=get_user&username=support@bluebillywig.com&password=Hdjsd7ds32f23FAKel923K

Successful authentication

[xml]
<?xml version="1.0"?>    
<user id="35" name="testuser@bluebillywig.com" firstname="Test" lastname="User" gender="male" email="support@bluebillywig.com">

Failed authentication

[xml]
<?xml version="1.0"?>    
<response code="404" error="true">no user context or user is not authenticated</response>

Checking a VMS session

To check whether the session is still valid the checkSession action is used.

Request
/api/bbauth?action=checkSession

Result
A XML response is returned, containing a message and code whether the session still exists.

Example
/bbauth?action=checkSession

[xml]
<?xml version="1.0"?>
<response code="200" error="false">a valid session exists</response>

Logoff from the VMS platform

To end a VMS session, the logoff action is used.

Request
/api/bbauth?action=logoff

Result
The result will show whether the action was successful or failed.

Example
/api/bbauth?action=logoff

[xml]
<response code="200" error="false">the session has been destroyed</response>