authlogin v1.2.1
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.