1.2.1 • Published 6 years ago

authlogin v1.2.1

Weekly downloads
-
License
ISC
Repository
github
Last release
6 years ago

Authlogin API

Hey there! You're probably here to make your apps better with Authlogin, a simplified and secure login service from Authbase. We're here just to tell you how it works. It's simple - don't worry!

Register an App

Create an Authbase account (if you haven't already), log in, and navigate to https://authbase.co/app/new. Add a name for your app (this can't be changed, so make it good), click 'Create App', and your app has been made. You can add an App IMG and description in the Settings page.

Then go to the 'Addons' tab in your app page, and then click 'Add to {yourApp}' under the Authlogin app item. This will then add Authlogin to your app, enabling you to use the API.

You will also need your App ID and App Secret, found under the 'Info' tab.

Important: you should never show your App Secret to anyone.

Installing the Server API

JS API

You can install the Authlogin API from npm by running:

npm install authlogin --save

REST API

We are working on a Rest API, but it has not yet been released.

Installing the Client API

CDN

We offer the client API through the jsdelivr CDN. Add a script tag with a 'src' attribute of:

Latest: https://cdn.jsdelivr.net/npm/authlogin@latest/authloginClient-latest.js

1.2.1: https://cdn.jsdelivr.net/npm/authlogin@1.2.1/authloginClient-latest.js

Download

You may also download the latest version of the Authlogin client API at:

https://authbase.co/cdn/js/authloginClient_latest.js

Setting Up

Installation

Client API

On pages with the login button present, the following code will need to be present in the <head></head> tags:

<script src="https://authbase.co/cdn/js/authloginClient-latest.js"></script>
<script>
    var AuthloginClient = new Authlogin({
        appID: "yourAppID"
    });
</script>

Server API

On your server, you will need to write the following code to setup the API:

var Authlogin = require("authlogin");

var AuthloginServer = new Authlogin({
	appID: "yourAppID",
	appSecret: "yourAppSecret"
});

AuthloginServer.authenticate(function(data) {
	if(data.response == "OK"){
        console.log("[AuthloginServer] App Authentication was successful.");
    } else {
        console.log(data);
    }
});

Setting Endpoints

Authlogin requires two endpoints in order to function. Click the 'Authlogin' tab in your app page to set the endpoints for your app.

Login Callback URL

This URL is where your user will be redirected to after they have logged in through Authbase. This may be your homepage, or your userpage. A full URL is needed, for example:

https://www.example.com/completeLogin

User Data POST URL

This URL is where the following information will be submitted via a POST request to:

{
  "for": {
    // These two parameters are stored as cookies on the clients browser with the prefix 'al_' (e.g. al_lcID).
    "lcID": 'Kq0RhUAazN',
    "lsID": '1VoPZU5LCu'
  },
  "data": {
    // These can be used to identify the user through the backend.
    "clientID": 'FueRouWqy4',
    "sessionID": 'yX4nTaswBN'
  }
}

It is recommended that this URL is /al/handleLogin as it is used throughout this documentation. A full URL is needed, for example:

https://www.example.com/al/handleLogin

Using the Client API

Setting the Login Button

Authlogin requires you to set the login button so it can automatically create a secure login ID as soon as the user clicks the 'Login' button. To do this, you must enter the following code to be run as soon as the DOM loads.

AuthloginClient.setButton({
    className: "al-button"
});

The 'className' attribute should match the class name of the <a> tag your button is associated with, for example:

<a class="al-button">Login</a>

Setting the Logout Button

To allow your users to login, you can use the following code:

AuthloginClient.logout();

You can use this code in an <a> tag, like so:

<a href="#" onclick="AuthloginClient.logout();">Logout</a>

Using the Server API

Handling Login Data (Server)

When a user logs in with Authlogin, a request is sent to an endpoint on your server. To setup this endpoint, use the following code. No customization is needed, but the framework you use to handle endpoints may differ. Express JS is used in this example, although other frameworks may be used.

router.post("/al/handleLogin", function(req, res, next) {
    res.setHeader("Access-Control-Allow-Origin", "https://authbase.co");
    // Here you would send the client ID and the session ID of the user to the server, use their.
    const clientID = req.body.data.clientID;
    const sessionID = req.body.data.sessionID;

    const lcID = req.body.for.lcID;
    const lsID = req.body.for.lsID;
    
    AuthloginServer.listenForCredentials(req.body, function(data0) {
        res.send(data0);
    });
});

This endpoint is required. If it is not successfully setup, your users will encounter an error when they try to click 'Authorize App' on the Authlogin site. When developing locally, use a service like ngrok so Authbase can send the request to your locally developed app.

Authenticating a user from their IDs

To authenticate a user from their IDs (Client ID, Session ID), you can use the following function to verify the user.

AuthloginServer.authenticateUserFromIDs({
    clientID: clientID,
    sessionID: sessionID
}, function(data){
    if(data.response == "OK"){
        // user authenticated
    } else {
        // user not authenticated or an error occurred
    }
});

Authenticating a user from their LIDs

To authenticate a user from their LIDs (Local Client ID, Local Session ID), you can use the following function to verify the user.

AuthloginServer.authenticateUserFromLIDs({
    al_lcID: al_lcID,
    al_lsID: al_lsID
}, function(data){
    if(data.response == "OK"){
        // user authenticated
    } else {
        // user not authenticated or an error occurred
    }
});

Retrieving user data from their IDs

To retrieve a users data from Authbase such as their username and profile image from their IDs (Client ID, Session ID), use the following function.

AuthloginServer.getUserDataFromIDs({
    clientID: clientID,
    sessionID: sessionID
}, function(data){
    if(data.response == "OK"){
        const username = data.data.username;
        const unixJoined = data.data.unixJoined;

        const name = data.data.profile.name;
        const bio = data.data.profile.bio;
        const profileImgURL = data.data.profile.profileImg;
        const isVerified = data.data.profile.verified;
    } else {
        // user not authenticated or an error occurred
    }
});

Retrieving user data from their LIDs

To retrieve a users data from Authbase such as their username and profile image from their LIDs (Local Client ID, Local Session ID), use the following function.

AuthloginServer.getUserDataFromLIDs({
    al_lcID: al_lcID,
    al_lsID: al_lsID
}, function(data){
    if(data.response == "OK"){
        const username = data.data.username;
        const unixJoined = data.data.unixJoined;

        const name = data.data.profile.name;
        const bio = data.data.profile.bio;
        const profileImgURL = data.data.profile.profileImg;
        const isVerified = data.data.profile.verified;
    } else {
        // user not authenticated or an error occurred
    }
});

Retrieving user data from their username

To retrieve a users data from Authbase such as their username and profile image from their username, use the following function.

AuthloginServer.getUserDataFromUsername({
    username: username
}, function(data){
    if(data.response == "OK"){
        const username = data.data.username;
        const unixJoined = data.data.unixJoined;

        const name = data.data.profile.name;
        const bio = data.data.profile.bio;
        const profileImgURL = data.data.profile.profileImg;
        const isVerified = data.data.profile.verified;
    } else {
        // user not authenticated or an error occurred
    }
});

Retrieving a users IDs from their LIDs

The LIDs (Client Local ID, Session Local ID) is what is used to identify the user on their browser. This is then sent to the server, and Authlogin finds their appropeate Client ID and Session ID.

The Client ID is used to identify the user across the backend, such as when the user makes a post, their Client ID can be used to identify them as the author.

The reason the Client ID of the user is not equal to the Local Client ID of the user is for security.

If the user is logged into two different devices, a computer and a mobile for example, then if the users computer is compromised, then the Local Client ID and the Local Session ID of the app on the computer can be revoked remotely so requests to the Authlogin API are no longer furfilled for the compromised device.

To find the Client ID and the Session ID of a user through their LCID and their LSID, use the following function.

AuthloginServer.getIDsFromLIDs({
    al_lcID: al_lcID,
    al_lsID: al_lsID
}, function(data){
    if(data.response == "OK"){
        const clientID = data.data.clientID;
        const sessionID = data.data.sessionID;
    } else {
        // user not authenticated or an error occurred
    }
});

Handling Page Permissions (Server)

You may use Authlogin to grant access to certain pages on your site, depending on the user or if they're logged in our not. Use the following code inside of your code to handle endpoints. In this example, we will use the index page and we will use the Express JS framework, but other frameworks may be used.

'req.cookies' is the Express JS method to get the cookies from the browser in order to verify the client, you may need to use a different method to get the users cookies from the request.

If you wish to manually set the 'req.cookies' parameter, use a JSON object in the following format:

{
  "al_lcID": "lcID",
  "al_lsID": "lsID"
}
router.get("/", function(req, res, next) {
    AuthloginServer.getUserDataFromLIDs(req.cookies, function(userData){
        if(userData.response == "OK"){
            // The user is logged in.
            res.render("index", { 
                title: "MyApp",
                userData: userData.data
            });
        } else {
            // The user is not logged in.
            res.render("index", { 
                title: "MyApp",
                userData: null
            });
        }
    });
});

Support

Have any issues using the API? Feel free to email us at support@authbase.co.

Licence

The Authlogin API is licenced under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International Licence. Read more about it here.

1.2.1

6 years ago

1.2.0

6 years ago

1.1.6

6 years ago

1.1.5

6 years ago

1.1.4

6 years ago

1.1.3

6 years ago

1.1.2

6 years ago

1.1.1

6 years ago

1.1.0

6 years ago

1.0.5

6 years ago

1.0.4

6 years ago

1.0.3

6 years ago

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago