LiveAuth API

This document provides details and examples of the idibu LiveAuth API and LiveAuth JavaScript library usage.

LiveAuth API enables users to authorise idibu for posting job adverts on destinations that require OAuth. Currently, such destinations are social networks like Facebook, Twitter, or LinkedIn. Authentication and authorisation are achieved through the OAuth flow, where the user needs to be presented with a trusted web page ("3-legged" OAuth flow).

LiveAuth provides a consistent API across all supported destinations. On top of that, idibu maintains a verified application registration on each destination so that a consumer of the LiveAuth API does not have to. In fact, at the time of writing, idibu does not provide the means to customise the application used.

LiveAuth JavaScript library

The JavaScript library provides a simple implementation of common interactions with the LiveAuth API in a browser setting. It can be used directly or as a basis for custom integration.

Other applications, like native desktop or mobile, need to integrate with the LiveAuth API directly. Please note that the runtime used needs the ability to display a web view for the purpose of handling the OAuth flow.

Compatible Portals

Posting destinations that support LiveAuth can be obtained through the liveauth field from the Get Board Data response.

Installation (JavaScript users)

Include the following import in the page header:

<script src="//www.idibu.com/clients/api/liveauth/client.js"></script>

JavaScript Library is provided as a vanilla ES5-compatible script, meant to be linked to directly in a web page. At the time of writing, no npm package or other type of module is available.

Authentication

An authentication hash (token) is needed to interact with the LiveAuth API.

An authentication hash is generated by taking the clientId and expires values, concatenated with a hyphen (-), and hashing it using the HMAC SHA256 algorithm with a secret key.

clientId is an integer identifying a customer account in idibu - refer to the Service Management Webservice.
expires is an integer representing a UNIX timestamp in seconds. It indicates the maximum time for when the hash is valid and should be set in the future.

The secret key is unique to the domain from which your requests will originate - and can be obtained by contacting idibu and specifying the domain(s) that you will utilize to perform the connection. If you are connecting to the API directly from the back-end, make sure to include a Referer HTTP header with the correct domain.

Important: Never reveal the Partner secret key to the end-user. The authentication hash is meant to be generated server-side.

Example of generating a hash in PHP:

$clientId = 42;
$expires = time() + 3600; // an hour into the future
$secretKey = "whatissixtimesnine";

$hash = hash_hmac(SHA256, "$clientId-$expires", $secretKey);

Initialisation (JavaScript users)

The library is initialised and configured by creating a new LiveAuthClient object. The constructor requires a configuration object with at least the auth property.

var liveAuthClient = new LiveAuthClient({
    auth: {...}
});

The auth property must be an object with the following properties:

name	type	description
`client`	integer	ID of the idibu account
`expires`	integer	a UNIX timestamp in seconds
`hash`	string	a hash created using the method described in Authentication section above

Example of a complete initialisation:

var liveAuthClient = new LiveAuthClient({
    auth: {
        client: 42,
        expires: 989539200,
        hash: "6b1a62617de259688c021c6d98efaca588c772f9ee8ea3092fb3d5323e66ba29"
    }
});

Making requests (API users)

LiveAuth API provides the following endpoint:

https://www.idibu.com/clients/api/liveauth/:actionName

Where :actionName is one of the following: test, status, login, logout, complete-info. Please refer to the notes in the Usage section below (action names correspond to the method names of the JavaScript Library object).

The endpoint accepts regular HTTP GET requests with parameters encoded in the URI query part.

All requests require at least the three parameters:

name	type	description
`client`	integer	id of the idibu account
`expires`	integer	a UNIX timestamp in seconds
`hash`	string	a hash created using the method described in the Authentication section above

For example:

GET https://www.idibu.com/clients/api/liveauth/test?client=42&expires=1580608922&hash=6b1a62617de259688c021c6d98efaca588c772f9ee8ea3092fb3d5323e66ba29

Further usage examples will skip the protocol and host parts of the URI, as well as mandatory parameters for brevity. For example, the request above would be shortened to:

GET /clients/api/liveauth/test

The response is returned as a JSON object by default.

JSONP

The API supports returning data as JSONP for older browsers that do not support CORS policies.

This mode is used by the JavaScript Library for maximum compatibility, but it is not required when targeting modern browsers or non-browser runtimes.

This mode is enabled by adding a callback parameter to the request with the name of a JavaScript function available in the global scope. The response will be wrapped as a function call for the function with the provided name.

Please refer to publicly available resources on JSONP for further information.

Usage

Features of the library are accessed by calling methods of the LiveAuthClient object. All methods take a callback function as their last parameter and may take a configuration object with name parameters as their first. The list of available methods is below.

The language of this section is targeted at JavaScript Library usage, but the information is relevant to the API usage as well. Information specific to the API usage is provided as needed, and the implementation of the JavaScript Library can be referred to for additional details.

`test`

This method can be used to test that the authentication works.

The function takes a callback as it's the only parameter that is called back with a hello world string.

Example:

liveAuthClient.test(function(message) {
    console.log(message);
});

Console output:

"hello world"

API usage

GET /clients/api/liveauth/test

`getStatus`

This function allows checking the posting profile a given idibu profile is set to post as on a given LiveAuth portal.

In addition to the callback, it takes an object with the following properties:

name	type	description
`portal`	integer	an idibu id of the Portal - refer to the Portal Management Webservice
`profile`	integer	an idibu id of the account's User - refer to the User Management Webservice

The callback function gets passed an object with some or all of the following properties:

name	type	description
`signed`	boolean	`true` if the posting profile is active and can be used for posting
`isProfile`	boolean	`true` if the posting profile belongs to the User, `false` if the parent (Team, Office, or Admin) profile is used
`name`	string	posting profile name on the portal
`picture`	URL	location of the profile image from the portal

Example:

liveAuthClient.getStatus({
    portal: 4,
    profile: 2
}, function(status) {
    console.log(status);
});

Console output:

{
   "signed": true,
   "isProfile": true,
   "name": "John Doe",
   "picture": "http://social.network.com/img/c82f36R2.jpg"
}

API usage

GET /clients/api/liveauth/status?portal=4&profile=2

`login`

This function opens a pop-up allowing the user to log in to the posting profile.

It can be called with just the portal parameter, and in this case, the board credentials are passed back to the callback function after the authentication is complete. The credentials need to be later saved in idibu - refer to the Subscription Management Webservice.

Alternatively, it can be called with the link and id parameters - link specifying the level of login (global, office, team, profile) and id specifying the id of the specified Office, Team, or User (id is required for all except global, in which case the client parameter of auth is used). In this case, the board credentials, in addition to being returned, are also automatically saved in idibu.

name	type	description
`portal`	integer	an idibu id of the Portal - refer to the Portal Management Webservice
`link`	string	either `global`, `office`, `team`, `profile`
`id`	integer	an idibu id of the Office, Team, or Profile, respectively - refer to the User Management Webservice

The callback is passed an object with idibu extra field names as its keys and portal credentials as values.

Example:

liveAuthClient.login({
    portal: 4,
    link: "profile",
    id: 2
}, function(credentials) {
    console.log(credentials);
});

{
   "portal_6_token": "NDa3rcnc33y983v983bv9y9223c9y3"
}

API usage

GET /clients/api/liveauth/login?portal=4&link=profile&id=2

Calling the endpoint will return the following JSON object:

{
   "url": "https://example.com/oauth/123456",
   "token": "161bc25962da8fed6d2f59922fb642aa"
}

At this point, the user needs to be presented with a pop-up or a web view of the website from the returned url field.

Please note the URL will lead to a website operated by the posting destination system - it will be outside of idibu's scope.

Once the pop-up or web view is closed, another request to the API needs to be made with the token parameter:

GET /clients/api/liveauth/complete-info?token=161bc25962da8fed6d2f59922fb642aa

This request will return the final result of the login. In the JavaScript Library, this part - handling the popup and the second request - is automated.

`logout`

This function takes the same parameters as login but removes the specified credentials from idibu. On success, a callback is called without any parameters.

name	type	description
`portal`	integer	an idibu id of the Portal - refer to the Portal Management Webservice
`link`	string	either `global`, `office`, `team`, `profile`
`id`	integer	an idibu id of the Office, Team, or Profile, respectively - refer to the User Management Webservice

Example:

liveAuthClient.logout({
    portal: 6,
    link: "profile",
    id: 9
}, function() {
    console.log("Done!");
});

Console output (after successful logout):

"Done!"

API usage

GET /clients/api/liveauth/logout?portal=4&link=profile&id=2

Configuration (JavaScript users)

The configuration object for LiveAuthClient might contain additional properties (besides auth) to customize its behaviour:

name	type	default value	description
`endpoint`	url	`https://www.idibu.com/clients/api/liveauth/`	an endpoint used for API calls
`callbackParam`	string	`callback`	a name of the JSONP callback param used on the endpoint
`timeout`	integer	`5000`	time in milliseconds after which the requests are considered timed out
`window`	string	`width=800,height=600`	a configuration passed to the `window.open` method
`onError`	function	`(message) => { console.error(message); }`	a function called with the error description upon encountering an error

Complete test page example (JavaScript users)

<!DOCTYPE html>
<meta name="x-liveauth-client" content="42">
<meta name="x-liveauth-expires" content="989539200">
<meta name="x-liveauth-hash" content="f4a04f87cabf65ed55a2db9da2159cd7">
<button id="test">Test</button>
<script src="https://www.idibu.com/clients/api/liveauth/client.js"></script>
<script>
    var getMeta = function(name) {
        return document.getElementsByName(name)[0].getAttribute("content");
    }

    var liveauth = new LiveAuthClient({
        auth: {
            client: getMeta("x-liveauth-client"),
            expires: getMeta("x-liveauth-expires"),
            hash: getMeta("x-liveauth-hash")
        }
    });

    // Value of the hash needs to be computed on the back end,
    // see Authentication section above.
    //
    // In this simple example, the values of the hash,
    // as well as the client id and expires timestamp,
    // are assumed to be rendered by the back-end into the HTML meta tag,
    // but they can also be embedded in other ways or fetched through XHR.

    document.getElementById("test").onclick = function() {
        liveauth.test(function(message) {
            console.log(message);
        });
    }
</script>

LiveAuth JavaScript library​

Compatible Portals​

Installation (JavaScript users)​

Authentication​

Initialisation (JavaScript users)​

Making requests (API users)​

JSONP​

Usage​

test​

Example:​

Console output:​

API usage​

getStatus​

Example:​

Console output:​

API usage​

login​

Example:​

Console output (after successful login):​

API usage​

logout​

Example:​

Console output (after successful logout):​

API usage​

Configuration (JavaScript users)

Complete test page example (JavaScript users)

LiveAuth JavaScript library

Compatible Portals

Installation (JavaScript users)

Authentication

Initialisation (JavaScript users)

Making requests (API users)

JSONP

Usage

`test`

Example:

Console output:

API usage

`getStatus`

Example:

Console output:

API usage

`login`

Example:

Console output (after successful login):

API usage

`logout`

Example:

Console output (after successful logout):

API usage