Overview

The client library for awesome-auth used to register and authenticate users and securely connect to endpoints via websocket. It consists of two classes, AwesomeAuth and AuthSocket.

• AwesomeAuth is used to check authentication status, get info about the current user and register a new user to your application.
• AuthSocket is used to securely make websocket calls to your http or websocket endpoints.

Get the javascript client

The javascript client is available on npm. Browserify is recommended.

npm install awesome-auth-client

Other options include manually pulling down the most recent release from the repo or referencing the hosted latest version. Include the AwesomeAuth javascript client in your web page to make the AwesomeAuth and AuthSocket modules available.

<script src="awesome-auth.js"></script>

Authentication status

To check user authentication status and identify the current user, create a new instance of the AwesomeAuth object and pass it an options JSON object.

new AwesomeAuth(opts)

• appName - the name of your mapping file
• onAuthStatusChange - function that is called with the authentication status when the user's authentication status changes.
  • result.user - If the user has confirmed, this will populated with the user defined in the getUserInfo function
  • result.status - Contains a string representing a failure to authenticate. May be 'user-not-found' or 'unconfirmed'.
  • result.error - If there's a system error during processing

var awesomeAuth = new AwesomeAuth({appName: 'pocket', onAuthStatusChange: function(result){
    if (result.user){
        console.log("Logged in user:", result.user)
        window.currentUser = result.user
    }
    else if (result.status) {
        console.log("Need to register or confirm registration", result.status)
    }
    else if (result.error) {
        console.log("System error", result.error)
    }
}});

Registration

awesomeAuth.register('[email protected]', function(err, token){
    if (err) console.log("err", err);
    if (token) console.log("token", token);
});

awesomeAuth.register({email: '[email protected]', customerName: "Bain", person_id: 1594}, function(err, token){
    if (err) console.log("err", err);
    if (token) console.log("token", token);
}));

This registers a user to the system and sends them a confirmation email. The optional callback function can report that a token was generated and sending an email has been attempted.

AwesomeAuth will continuously poll until they have clicked the link in the email. Once they have confirmed, the onAuthStatusChange callback will return the full user defined in the getUserInfo function.

The data passed to register gets sent to the getUserInfo function, so include anything you need to identify this user.

Resend confirmation

If a user misses the initial confirmation email, they can self-serve and trigger the sending of another.

awesomeAuth.resendConfirmation(function(err){
    if (err) {
        console.log("Error while sending confirmation email", err);
    } else {
        console.log("Confirmation email sent!");
    }
});

Log out

Logging a user out destroys their token. They have to re-register to get back into the system.

awesomeAuth.logOut();

This will trigger the onAuthStatusChange callback with the status "user-log-out". ###Using the authorized socket To initialize, create an instance of AuthSocket and pass in the options object to the constructor.

var opts = {
    appName: 'pocket',
    urls: ["http://query.glgroup.com/epiquery/"]
};

var mySocket = new AuthSocket(opts);

opts

• appName- name of the app, matching the name of the mapping file.

• urls - array of urls (protocol and hostname only) to which you want to connect. The host names of the url(s) specified here must match the hosts names specified in the mapping file validHosts property. If your destination has multiple deployments you can specify them all here ("http://east.glgresearch.com/myDest/", "http://west.glgresearch.com/myDest/", etc)

After it has been created, it behaves exactly like a normal websocket. All of the normal Websocket events are exposed on the AuthSocket:

mySocket.onerror = function(error){
    console.log(error)
};

mySocket.onmessage = function(message) {
    console.log("Message from destination server", message)
};

mySocket.onclose = function(event){
    console.log("Connection closed")
};

mySocket.onopen = function(){
    console.log("Connection opened", socket.currentUser)
};

###Sending a message to an HTTP endpoint

HTTP messages will use the send method on the socket and pass an options object.

options verb - HTTP method path - the path to your destination relative to the url(s) provided when creating the socket callback - function that handles results from your call

var opts = {
    verb: 'GET',
    path: 'person/getPersonByLoginName.mustache?Login=glgroup\\khughes'
    callback: function(results) {
        console.log("Here are my results!", results)
    }
}
mySocket.send(opts);

Working offline

There's a development mode that you can use to work completely disconnected from AwesomeAuth. You can use it to fake out a user and to communicate with WebSocket and HTTP servers.

Please note, it has limited functionality. You can't register or log out and it's not performing any authentication. It also doesn't connect to basic auth protected services.

Here's an example of faking out a user.

var myUser = {
  name: "Nick Swarr",
  email: "[email protected]",
  id: 123456
};
  
var awesomeAuth = new AwesomeAuth({user: myUser, authenticationCallback: function(result){
  console.log("Just got my user back!", result.user);
}});

Here's how you set up a local socket.

var authSocket = new AuthSocket({localDev: true, urls: ["ws://localhost:5555/"]});
authSocket.send("This talks directly to my socket server")
``