Code

There is very little code that the merchant has to do in order to use Simply Sign In. If you are merchant who is now implementing our system, ask your developers to read this section carefully.

In this section the word "you" the merchant (or his/her software developer... basically one who is responsible for implementing the code) . This sections is NOT meant for the user who got authenticated

When a merchant takes an account with us; the following information is setup in your configuration with us:

1. The Merchant ID (MID). This is at least a 3 character ID which must be unique (When you provide this, our server will check that it is unique) This has to be done by the merchant. Pick something that is related to your system. This ID will be seen by all and sundry. It is important that they see it; in fact and when they type out the SMS that ID would be there in it. So this ID should not be very complex with chance of mis-interpreting the spelling. E.g. Think carefully before using I instead of L or zero instead of O, etc. in the ID.

2. The Merchant-SSI shared secret (MSSI): This is set automatically by us on successful registration. It will be shown to you. Keep this secret really secretive ! It must be NEVER exposed in any front-end code!

3. The Receiver code (RC) is to represent the receiving server which would be used to receive the message sent by your user. Keep this also as a secret. If you use our built-in receiver, then the code would be "SR1" (for SMS based messages) and "SR2" (for email based messages) But if you want to implement your own receiver, then you will have to first set that up separately; obtain an receiver code for it and then enter that code in your configuration.

4. The initial message (MSG1) that is displayed at the top on the user entry page. This would be something like: "Sign-Up or Sign-In into your own account at Simply Sign In" or words to that effect. You can also use a <br> and add a sub-title. Note: Only a few HTML elements are allowed here.

5. The CORS URL (CORS) Our system will allow embedding of our entry page as an iframe into your own website pages at this URL.

6. The Virtual Login URL (LOGURL) This is the url to which the initial page would get redirected to on successful login.

7. The Keyword (MSGKEY) -- This is one simple word which will be used right at the front of the message sent by the user.

Now that you know what all fields have been set in your configuration, your system's coder has to do very little work to take advantage of this. But before that happens, you must ensure that the receiving server must be set correctly, and that particular server would also have setup correctly too. This is explained in another chapter. After that, the system can be put to use. You should either redirect the user who is doing a sign-up or sign-in to this URL

https://app.simplysign.in/api/v1/frontend/<MID>

If you do not like taking the user to another website, feel free to embed that link into an iframe at your site. But please note that it must be embedded on the same site that you gave for <CORS> The user will have to follow the instructions that is displayed on that frontend page. If your receiving server is for SMS then he/she would have to send the SMS as explained on that page. if your receiving server is for an EMAIL then he/she would ahve to send an Email as explained on that page

Redirecting the authenticated user to your server

Once the user is authenticated by your system; Simply Sign In will redirect the user to <LOGURL>. It will have two additional query string variables: "prox" and "merchash" that you need to use as explained below. Let's say the <LOGURL> was:

https://example.com/api/v1/virtuallogin

Then the URL to which our system will redirect the page would be:

https://example.com/api/v1/virtuallogin?prox=<prox>&merchhash=<totpsecrethash>

In the above redirection URL <prox> stands for the proxy of the user's originator ID. in case it is from SMS, then the originator ID would be the proxy of the phone number that the user had used. In case the user had used the email route (and the receiver server was handling emails) then the originator ID would be the proxy of the email address the user had used. To remind you what a proxy is? It is simply the SHA256 of the originator ID. Nothing more.

The 2nd parameter: <totpsecrethash> would be the SHA256 of the following strings joined together:

<MID> + <MSSI>+ <prox> + <totp>

Now as a developer you may start scratching your head here. Why? Because you know the value of <MID>, <MSSI> and <prox> but how to get the value of <totp>?

After all, the <totp> was NOT passed to the redirected URL! Worry not. Your server will have to again rework the TOTP at your end, using the following algorithm, as seen in the JS code fragment below:

const totpsecret = $security.sha256(<prox> + <MSSI>);
const totp = generateTOTP(totpsecret,300)); 

In the above pseudo-code generateTOTP(...) function is the standard TOTP generation function. It is exactly the output given by the "oauthtool" command in Ubuntu

oathtool -d 6 -s 300 --totp

So at this point in time, your code would be able to recalculate your version of <totpsecrethash> and that should be exactly equal to the same parameter passed on the URL.

The above check must be performed at your server to rule out any chance of inauthentic usage such as replay attacks.

If it indeed both <totpsecrethash> are same (the one we gave and the one you re-calculated), that means you can be quite rest assured that the user (whose <prox> was provided) has been authenticated. It goes without saying that the checking of <totpsecrethash> should NOT be made using browser code, but must be done at your system's backend server! At this point in time, your system should take over and do a login or registration; as needed.

As both the <prox> and <totpsecrethash> are exposed on the URL of the browser, it is strongly recommended that you redirect the user once again really fast; so that the user cannot copy them and pass it on to the friendly neighborhood hacker who was phishing for it! No harm if the user does that... but why entertain hackers, right? Why is this so effective? As you know; TOTP is a time-sensitive one-time-password; and since all this should ideally happen within the time-frame of around 3 minutes, it becomes a serious deterrent for hackers to re-calculate that <totpsecrethash> in order to gain entry into an account of your system.

The user is now authenticated and its proxy is available at your server. What should happen next at your server?

This depends on what is being coded on your server. The basic idea when you reach this stage is to take the authenticated <prox> which has now reached you as the authenticated ID (username) of the user. Let us list some options:

1. If you are developing your own software for your server then ask the developers to utilize the above <prox> value for registrations and logins. This is quite easy for all technologies available for developing code from scratch. For e.g. If you are developing using the excellent open source backend server system called "Pocketbase" it is not even one minute of work. This is the option to use; if you are using the Simply Sign In way to say; open a cabin door which has an IP enabled lock, for example.

2. If you are implementing some open-source software for your own use, then you will have to read their documentation to see how to register a new user into that system from that software's backend. Almost all open-source software would give you a way to do register (i.e. create) a new account via some API or server cli (command-line interface). However some may only allow the backend to register but will not allow to perform a login on behalf of a pre-authenticated user. Such a system would insist that registered users use the frontend of the system to allow a user in later on, after registration. If you use Simply Sign In only to create registrations (and not for login) then that you are good to go. In that case you should ask the new user to create the username + password (and any other additional info that the system needs)

3. If you are developing a set of different SaaS applications and you want each of users to be able to use ALL of them, using the same credentials; then the best route is to first create an identity of the user at an OpenID Connect server as the very first step. What is OpenID? It is a system that allows a user to enter an OpenID enabled website/SaaS application by just specifying one unique URL belonging to the user; which passes on the identity of the user to the place he/she is entering. If this is what you wish to do; after Simply Sign In identifies an authenticated user; instead of taking the user directly to your end application, the redirection page should be to a piece of code which will create the equivalent identity at your own OpenID Connect server. The simplest way to do it is using the excellent, and very simple; SimpleID from https://simpleid.org It is written in PHP and it can efficiently do its work on some domain (or sub-domain) that you have. It is extremely easy for a coder to create an identify file for each user after Simply Sign In sends the authenticated <proxy> Why? Because SimpleID stores each identity for a user in a file specifically for that user. (Such a file should not be accessible from the regular Internet. Read their docs) No messing around with databases, etc. Each identity then gets recognized by its own special OpenID URL. Once the OpenID identities are created for all the users of your system; all your users can then use their own respective identities in all the systems that you are using in house, via OpenID. Of course; it goes without saying, all of them must have the OpenID way of access.

4. There are other kinds of identity providing systems. OpenID is just one of them. You could use LDAP, SAML, and several others. We'll add the documentation of those as and when we encounter use-cases for them. Do let us know your own experience. It would be nice to know how you finally allowed the user authenticated by Simply Sign In, to use systems at your end.

Simply Sign In can also be used to authenticate users on an Intranet

It is extremely easy to use Simply Sign In for authenticating users on your own private Intranet. The way to do this is very easy. Use Ngrok or some other tunelling service to expose one of the nodes of the Intranet to the wide world. That node should run a localhost server. The above <LOGURL> should be pointing to a particular page on that node's server. Now, when that page receives the authenticated <prox> your code should then use that node's server to pass register/login the user on to the Intranet system you have implemented.