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:
  • options (object) –

    An object of following options:

    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="http://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:
  • 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.

    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.

Fork me on GitHub