JavaScript¶

The authomatic.js library is here to make your life even easier. It has a very tiny interface similar to it’s Python sibling. Yo can use it to:

Process the login procedure in a popup window.
Access protected resources in the most efficient way without any hassle.

Warning

The library is dependent on jQuery!

authomatic.setup(options)¶

Sets up all the library’s options.

Arguments:

Arguments:	options (object) – An object of following options: `authomatic.options.logging`¶ `bool` If `true` the library will log a lot of information to the console. Popup options: `options.popupWidth`¶ `int` The width of the popup in pixels. Default is `800`. `options.popupHeight`¶ `int` The height of the popup in pixels. Default is `600`. `options.popupLinkSelector`¶ `string` A jQuery selector specifying links that should be affected by `authomatic.popupInit()`. Default is `'a.authomatic'`. `options.popupFormSelector`¶ `string` A jQuery selector specifying forms that should be affected by `authomatic.popupInit()`. Default is `'form.authomatic'`. `options.popupFormValidator`¶ `function` A function which you can use to validate the form before the popup opens. It accepts the jQuery selected form. The popup gets opened only if it returns `true`. Callbacks: `options.onPopupInvalid`¶ `function` Called when the popup form doesn’t pass validation. Accepts the form selected with jQuery as the only argument. `options.onPopupOpen`¶ `function` Called when the popup gets open. Accepts the popup location URL as the only argument. `options.onLoginComplete`¶ `function` Called when the popup gets closed after the login procedure is complete. Accepts the `loginResult` object as the only argument.

options (object) –
An object of following options:

authomatic.options.logging¶

bool If true the library will log a lot of information to the console.

Popup options:

options.popupWidth¶

int The width of the popup in pixels. Default is 800.

options.popupHeight¶

int The height of the popup in pixels. Default is 600.

options.popupLinkSelector¶

string A jQuery selector specifying links that should be affected by authomatic.popupInit(). Default is 'a.authomatic'.

options.popupFormSelector¶

string A jQuery selector specifying forms that should be affected by authomatic.popupInit(). Default is 'form.authomatic'.

options.popupFormValidator¶

function A function which you can use to validate the form before the popup opens. It accepts the jQuery selected form. The popup gets opened only if it returns true.

Callbacks:

options.onPopupInvalid¶

function Called when the popup form doesn’t pass validation. Accepts the form selected with jQuery as the only argument.

options.onPopupOpen¶

function Called when the popup gets open. Accepts the popup location URL as the only argument.

options.onLoginComplete¶

function Called when the popup gets closed after the login procedure is complete. Accepts the loginResult object as the only argument.

authomatic.popupInit()¶

If you call this function, all <a></a> and <form></form> elements with class="authomatic" will open a popup on click/submit. By links the location of the popup will be the value of href attribute, by forms the value of action attribute with query string extracted from the form inputs.

<!DOCTYPE html>
<html>
   <head>
      <title>Login Popup Example<title>
      <!-- authomatic.js is dependent on jQuery -->
      <script type="text/javascript" src="https://code.jquery.com/jquery-1.9.1.min.js"></script>
      <script type="text/javascript" src="authomatic.js"></script>
   </head>
   <body>

      <!-- Opens a popup with location = "login/facebook" -->
      <a class="authomatic" href="login/facebook">Login with Facebook</a>

      <!-- Opens a popup with location = "login/openid?id=me.yahoo.com" -->
      <form class="authomatic" action="login/openid" method="GET">
         <input type="text" name="id" value="me.yahoo.com" />
         <input type="submit" value="Login with OpenID" />
      </form>

      <script type="text/javascript">
         authomatic.popupInit();
      </script>

   </body>
</html>

authomatic.access(credentials, url[, options])¶

Makes an asynchronous request to protected resource of a user.

Under the hood it tries to make the request as efficiently as possible with the aim to save your backend’s resources:

By OAuth 2.0 providers:
1. First a cross-domain XHR request is attempted.
2. If that fails it continues either with:
  - A JSONP XHR request but only if the provider supports it and the request method is 'GET'
  - Otherwise it will fetch the provider through backend.
By OAuth 1.0a providers the request must be signed using the consumer secret which cannot be exposed in the client, so every request goes first to the backend. Depending on provider the backend either:
- Fetches the provider and returns the result of the fetch.
- Returns signed request elements with which a JSONP XHR request is made.

Arguments:

Arguments:	credentials (string) – Serialized `Credentials` of the user. url (string) – URL of the protected resource. Can include querystring and template tags in the form of `https://example.com/api/{user.id}/profile`. options (object) – An object of following options. Note You can also specify all of these options in the `authomatic.setup()`. Values specified here will override the values specified in `authomatic.setup()` with the exception of callbacks. `authomatic.options.backend`¶ `string` URL of your login handler, or the handler where you call the `Authomatic.backend()` function. Warning This parameter is required by all OAuth 1.0a providers and also by some OAuth 2.0 providers. `options.forceBackend`¶ `bool` If true requests will be fetched through backend by all providers. `options.substitute`¶ `object` An object which will be used to replace template tags inside the `URL`. e.g. URL `https://example.com/api/{user.id}/profile` by substitute `{user: {id: '123'}}` will be rendered as `https://example.com/api/123/profile`. `options.params`¶ `object` The query parameters of the request. `options.headers`¶ `object` The HTTP headers of the request. `options.body`¶ `string` The body of the request. `options.jsonpCallbackPrefix`¶ `string` Some providers don’t support cross-domain requests. In such case the function tries a JSONP request and will generate a temporary callback in the global namespace with the name `'authomaticJsonpCallback#'` where `#` is an integer unique for every callback. You can change the default `'authomaticJsonpCallback'` to whatever you want by specifying it in this option. Callbacks: Warning Callbacks specified in `authomatic.setup()` will not be overridden by those specified here, but both will be called, whereas those specified in `authomatic.setup()` will be called first. `options.onBackendStart`¶ `function` Called when `authomatic.access()` contacts backend. Accepts a object of parameters which will be sent to the backend as the only argument. `options.onBackendComplete`¶ `function` Called when response returns from backend. Accepts `data`, `textStatus` and `jqXHR` as arguments in the specified order. `options.onAccessSuccess`¶ `function` Called when a successful response returns from provider. Accepts `data`, `textStatus` and `jqXHR` as arguments in the specified order. `options.onAccessComplete`¶ `function` Called when any response returns from provider. Accepts `textStatus` and `jqXHR` as arguments in the specified order.

credentials (string) – Serialized Credentials of the user.
url (string) – URL of the protected resource. Can include querystring and template tags in the form of https://example.com/api/{user.id}/profile.
options (object) –
An object of following options.

Note

You can also specify all of these options in the authomatic.setup(). Values specified here will override the values specified in authomatic.setup() with the exception of callbacks.

authomatic.options.backend¶

string URL of your login handler, or the handler where you call the Authomatic.backend() function.

Warning

This parameter is required by all OAuth 1.0a providers and also by some OAuth 2.0 providers.

options.forceBackend¶

bool If true requests will be fetched through backend by all providers.

options.substitute¶

object An object which will be used to replace template tags inside the URL. e.g. URL https://example.com/api/{user.id}/profile by substitute {user: {id: '123'}} will be rendered as https://example.com/api/123/profile.

options.params¶

object The query parameters of the request.

options.headers¶

object The HTTP headers of the request.

options.body¶

string The body of the request.

options.jsonpCallbackPrefix¶

string Some providers don’t support cross-domain requests. In such case the function tries a JSONP request and will generate a temporary callback in the global namespace with the name 'authomaticJsonpCallback#' where # is an integer unique for every callback. You can change the default 'authomaticJsonpCallback' to whatever you want by specifying it in this option.

Callbacks:

Warning

Callbacks specified in authomatic.setup() will not be overridden by those specified here, but both will be called, whereas those specified in authomatic.setup() will be called first.

options.onBackendStart¶

function Called when authomatic.access() contacts backend. Accepts a object of parameters which will be sent to the backend as the only argument.

options.onBackendComplete¶

function Called when response returns from backend. Accepts data, textStatus and jqXHR as arguments in the specified order.

options.onAccessSuccess¶

function Called when a successful response returns from provider. Accepts data, textStatus and jqXHR as arguments in the specified order.

options.onAccessComplete¶

function Called when any response returns from provider. Accepts textStatus and jqXHR as arguments in the specified order.