Authomatic
is an authorization / authentication
client library for Python web applications
inspired by Alex Vagin’s Simpleauth.
In fact, I almost named it Deadsimpleauth,
but that name would be too long
for a succinct library.

- Tweet

# 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.