SQL Authentication

Before starting with this section, make sure you've properly set up the server and have a TLS/SSL connection established to the server when connecting clients.

Creating accounts

With the proper server settings in place and an initialized database, clients can create accounts with the signup() function:

gopherClient.signup("bob", "password", null);

This will add an account to the database with the User name "bob", and password "password". The third parameter are the custom account info columns you wish to be set when signing a client up for an account. The third (custom account info columns) parameter must be an object where the keys are the names of existing columns, and the values are the information to store in that column. For example, say we've established two custom account info columns, email and dob:

gopherClient.signup("bob", "password", {email: "[email protected]", dob: "6-18-1992"});

Now, when we want to know if the sign up went well or something went wrong, we can use the events.signup listener:

gopherClient.addEventListener(gopherClient.events.signup, clientSignup);

function clientSignup(success, error){
    if(!success){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Successfully created account!");
    }
}

Deleting Accounts

A client can delete their account while they're logged off with the deleteAccount() function:

gopherClient.deleteAccount("bob", "password", null);

This will delete the account with the name "bob", using the password "password". The last parameter are the custom account info columns you wish to use for something when deleting an account. The last (custom account info columns) parameter must be an object where the keys are the names of existing columns, and the values are optional information to use in your server callbacks. For example:

gopherClient.deleteAccount("bob", "password", {email: "[email protected]"});

Your delete account server callback will now receive a map[string]interface{} that looks like: {email: "[email protected]"}. It will also get the info stored on the database in the email column, so you can, for instance, compare the two emails to check if the client also supplied the correct email address for the account.

Now, when we want to know if the delete went well or something went wrong, we can use the events.accountDelete listener:

gopherClient.addEventListener(gopherClient.events.accountDelete, accountDeleted);

function accountDeleted(success, error){
    if(!success){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Successfully deleted account.");
    }
}

Login

A client cannot login with SQL features enabled on the server unless they have an account, or are logging in as a guest. Once a client has created their account, they can supply their User name and password to login():

gopherClient.login("bob", "password", false, false, null);

This will log the client in under the User name "bob", using the password "password". The last parameter are the custom account info columns you wish to be sent to the server when logging a client in. The last (custom account info columns) parameter must be an object where the keys are the names of existing columns, and the values are optional information to use in your server callbacks. For example:

gopherClient.login("bob", "password", false, false, {email: "[email protected]"});

Your login server callback will now receive a map[string]interface{} that looks like: {email: "[email protected]"}. It will also get the info stored on the database in the email column, so you can, for instance, compare the two emails to check if the client also supplied the correct email address for the account.

To check for a successful login and catch any errors, just use the events.login event listener (example here).

Custom login column

If you have a custom account info column set as the login column, you can instead pass the value for that column you wish to find the account for. For example, say we have the custom account info column, email mentioned above. We set the custom login column as the email column, and now clients would enter their email as the login parameter:

gopherClient.login("[email protected]", "password", false, false, null);

The server will look for the account associated with the email "[email protected]" on the email custom account info column, and log the user "bob" in (assuming they supplied the right password).

Changing Passwords

To change their password, a client must be logged into their account and supply at least a new and the correct old password. This can be done with the changePassword() function:

gopherClient.changePassword("old", "new", null);

This changes the client account's password from "old" to "new". The last parameter are the custom account info columns you wish to be sent to the server when changing a password. The last (custom account info columns) parameter must be an object where the keys are the names of existing columns, and the values are optional information to use in your server callbacks. For example:

gopherClient.changePassword("old", "new", {email: "[email protected]"});

Your password change server callback will now receive a map[string]interface{} that looks like: {email: "[email protected]"}. It will also get the info stored on the database in the email column, so you can, for instance, compare the two emails to check if the client also supplied the correct email address for the account.

To check for a successful password change and catch any errors, just use the events.passwordChange event listener:

gopherClient.addEventListener(gopherClient.events.passwordChange, changedPassword);

function changedPassword(success, error){
    if(!success){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Successfully changed password.");
    }
}

Changing Custom Account Info

To change data in a custom account info column, a client must be logged into their account and supply at least the column data to change, and the correct password for the account. This can be done with the changeAccountInfo() function:

gopherClient.changeAccountInfo("password", {email: "[email protected]"});

This checks the current account's password against "password" and changes the client account's email column to "[email protected]". The second parameter are the custom account info columns you wish to change. This must be an object where the keys are the names of existing columns, and the values are optional information to use in your server callbacks.

Your account info change server callback will now receive a map[string]interface{} that looks like: {email: "[email protected]"}. It will also get the info stored on the database in the email column, so you can, for instance, compare the two emails to check if the client didn't supply the same email again.

To check for a successful info change and catch any errors, just use the events.accountInfoChange event listener:

gopherClient.addEventListener(gopherClient.events.accountInfoChange, changedAccountInfo);

function changedAccountInfo(success, error){
    if(!success){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Successfully changed account info.");
    }
}

Auto-Login (Remember Me)

Before you can use this feature, you must enable the required core server settings. With the settings in place, a client can now send a login() request with a rememberMe bool as true, and the server will make a login key pair that saves to the client's localStorage. To make ensure that subsequent visits logs the User in, you must set the events.autologInit, events.autologNoFile, and events.autologFailed listeners:

gopherClient.addEventListener(gopherClient.events.autologInit, autologInited);
gopherClient.addEventListener(gopherClient.events.autologNoFile, autologNoFile);
gopherClient.addEventListener(gopherClient.events.autologFailed, autologFailed);

function autologInited(){
    // Prevent any login tries until either the login, autologNoFile, or autologFailed
    // listener is triggered.
}

function autologNoFile(){
    // The client has no auto-log info stored. Enable the client to login
}

function autologFailed(){
    // The client's saved login info either expired, or was compromised
    // Prompt client to change their password and enable logging in.
}

With the "remember me" server settings enabled, events.autologInit will always get triggered directly after a successful connection to the server. If the client has not logged in on a previous session, events.autologNoFile will get triggered, and the client should be allowed to log in normally. Then on subsequent visits after logging in with "remember me" enabled, the client automatically logs in, triggering the events.login listener. Otherwise, if the auto-log errored for some reason, the events.autologFailed will trigger.

Note: If the events.autologFailed listener triggers, it's either because the client disconnected and disrupted the server when creating a new auto-log key, or the client's keys were compromised. It's best to assume the worst and prompt a password change after an events.autologFailed event.

Friending