pq documentation1.png

This is the first documentation on Peer Query alpha, and it covers into detail the entire login system powering Peer Query.

Steem Connect v2 is good and makes it easy to integrate secure Steem login into apps, in this documentation you will discover how Peer Query uses Stem Connect to handle login.

The current code and methods may not be perfect, but for the time being they work and are secure.

If you have a better system, consider contributing on Peer Query or via Utopian, Steem JS needs all the documentation and hacks it can get.

Important things to note

Steem Connect naming conventions

This part is very tricky and if we miss it, we might into problems even with a well written and functional code.

The core auth object is named: sc2, however we can put it into any variable using:

var api(or whatever name we choose) = sc2.Initialize({...}).

By default we would have used Steem Connect as:

sc2.setAccessToken(...)

sc2.me(function (err, result)

In the second case we will now use Steem Connect as:

api.getLoginURL(state);

api.me(function (err, res) {...});

Two "init" convention

SC2 does seem to support two initialization calls:

sc2.Initialize({ ....});

as officially documented here.

sc2.init({ ...})

as officially documented here.

How to setup Steem Connect

Create app

Here are the conventions I followed in setting up Steem Connect app for Peer Query:

use name that correlates to name of project - Peer Query is @peerquery.app
use .app extension to app, so Peer Query app is @peerquery.app
create the app using the account of the project; @peerquery creates @peerquery.app
allow for visibility of app in the app store for better credibility
setup logo for app, blank profile pictures for apps are not cool
add a little bio or description to enlighten users of the use of app
be responsible; not to setup redirects to some strange site to abuse user's trust

Set up redirect

This part is easy, all we have to do is to list the exact URLs that we expect the app to be potentially redirected after login.

So we have:

From my experience, wild cards do not work. So if we try a wildcard for dynamic URL like:

https://peerquery.com/@*

This link might be used for dynamic URLs such as user account pages, tags and post pages however Steem Connect v2 see to support only absolute URLs for security reason.

I will reveal the trick I use to handle redirects to such dynamic pages later, so read on.

Handle dynamic redirects

The Steem Connect v2 app setup requires absolute URLs, which means we cannot set wildcard links as possible login redirects.

Due to this not all redirects could be handled in the Steem Connect v2. app setup. For instance, when a user initiates login from a profile, a tag or a post.

By dynamic URLs I mean links that we cannot predict beforehand, links like:

user accounts: /@random-user,
post links: /random-tag/@random-user/random-permlink,
tag pages: /random-tag.

This means that if we want the use to be re-directed right back to the dynamic page that they were on prior to initiation login, then the browser must remember the last dynamic page they were on prior to initiation login.

For this system, Peer Query uses a simple cookies system to store the URL of every dymanic page that a user visits. This means that if we are on any dynamic page: account or post, then the system will store the URL of the page.

Again, account and post pages share the same redirect URL, which is /me.

Whenever a user initiates login and is redirected back to the page, the login system check to see if the user was redirected to the /me page.

If this condition is true, then the system simple fetches the last dynamic page from the cookie and redirects the user straight to it!

Note that this system could work for all dynamic links including post pages, tags and accounts; however on peer Query it is used only for post page and accounts.

Handling login

Where to store auth token

After successful login, the user's browser will be given a query string which contains information about the authorized user, the scope of authentications and the auth token. This generates a new challenge: how do we store this information securely?

Storing it off in a remote server is kind of criminal and completely out of question. The challenge is to store it right in the user's browser. We have three options them: local storage, session storage and cookie.

This is a very sensitive issue, as with access to the token, anyone can use use the account of the token holders to vote and post. Ideally, we would want to store the tokens in the local storage however it stores that data forever which is also not good even though usually the average tokens expires after a week, however they are not supported on all browsers,

The Session storage would have been ideal if it had allowed us to set when a content should expire, but since it does not then it is not very useful as it will clear the data once the user closes the browser.

Then we come to cookies, the oldest browser storage. The problem with cookies is that they will send the data back to the server with every request. This is not the very best very best place to store auth tokens, however due to its browser wide support and apparent security Peer Query currently uses it.

In the subsequent updates however we will use both Local Storage as the default and rollback to Cookies only if Local Storage is not supported.

Cleaning the address bar

We would have to find a way to remove to long Steem Connect query string from the user's browser's address bar. One option will be to reload to the page's path, ignoring the query string, however it might end up sending users to another URL or bore them with too many redirects.

Fortunately Javascript provides us with a feature with lets us trim the URL in the browser without directly affecting user experience.

Peer Query uses:

history.replaceState(null, null, location.pathname);

This clear the query string from the URL leaving only the pathname, however, this is only done after the query string has been processed.

Securing the auth code

Peer Query use the Javascript function .btoa() and .atob() to obstruct the SC2 query string info before stoing it. Note that this is not encryption, its only obstruction and can be processed backed by anyone using the same functions.

Placing the auth code

For the alpha version of Peer Query, the login system is stored in the modular top navbar. The top navbar is modular in the sense that there is only one of it, and all of its is loaded into all pages via JQuery via:

$("#navbar").load("/navbar.html");

We can write a separate login system for each page, or put it into a single JS file and load to all pages. However on Peer Query it is stored right in the navbar where main login components are.

How we handle logout

Reset Steem Connect

First we reset the Steem Connect app. This is very important, as without it Steem Connect will still consider the user as logged in until the user closes the browser.

Clear the auth tokens

Next the auth tokens are cleared the cookie by emptying the cookie.

This approach is the safest, and if the other login procedures fail to execute for whatever reason, still our users' account will be logged out and safe.

Reload page

On Peer Query the page is reloaded after logout. This makes it easier to reset components to their initial logged out state, since Peer Query is not built on any front end UI framework which stores states for login and logout.

In front end UI libraries like Angular, React or Vue, it may not be necessary to reload the entire page on logout, we would simply set the login scope or state to false.

Notify other windows

If users are logged in on multiple windows on the same browser, it would be necessary to notify them on the other windows that they should re-login or simple automatically logged them out there as well.

Currently Peer Query does not have this system in place but will do soon.

Cool stuffs we can do after login

Register users
Count login
Log sessions

More work is on the way!

The current state of Peer Query only reflect its temporary state. In the coming days I will include more updates, major dates and changes to the nature and structure of the code.

This documentation is linked in the ReadMe of Peer Query at commit 3cc57da7a13557a8cd9a4da65edb931a1914bee9.

Posted on Utopian.io - Rewarding Open Source Contributors

Sort:

Trending

[-]

fabien (62) 7 years ago

Thank you for documenting this! That's a great post. FYI there is another trick to pass variable on SC login. You can add the parameter state on your login url like https://steemconnect.com/oauth2/authorize?client_id=peerquery.app&redirect_uri=https%3A%2F%2Fwww.peerquery.com%2F&scope=vote,comment,custom_json&state=here_the_variable_you_want, once the user login he will get back to your site with the same parameter state. With this it's easy to redirect user to the page he were before login, this is exactly how we do that in Busy.org. Also you need to use sc2.Initialize( not sc2.init( the last one is depreciated it was used in old version of SteemConnect SDK but not anymore.

$0.05

2 votes

apam (44) 7 years ago

Nice

$0.00

Peer Query Documentation: How the SC2 login system works