Quick-Login

To test the Quick-Login Authentication capability of the broker, scan the code below with your TAG ID App or Neuro-Access App, or any app derived from these. If viewing the page from the same device as you use for the App itself, you can also click on the QR-code to sign in. You can download an app for logging in using any of the following links: TAG ID for Android, TAG ID for iOS, Neuro-Access for Android or, Neuro-Access for iOS. You can send us any feedback, via our Feedback page.

Web API

Quick-Login Web API exists in three versions: Web client only (no back-end), back-end protected, and in-session. In the web client only mode, results are delivered directly to the web client. The web client asks the user to login, and the web client receives the response directly, once the user has logged in. In this mode, no back-end is involved. In Back-end mode, on the other hand, login is done to a proprietary back-end, rather than the web client. It is the back-end who requires the credentials of the user. The Quick-Login feature calls the back-end as soon as the user has logged in. It also informs the web client, that the back-end has been informed, so it can refers its user interface. In session mode, information about the login is stored in the web session on the neuron processing the quick-login. This allows services running on the Neuron to use Quick-Login to get access to the login information on pages and script running on the neuron.

The following subsections describe these modes in more detail.

Web-Client only

To embed a Quick-Login feature in your web client page, without back-end integration, this mode is appropriate. The web client starts by making a request to the server to initiate Quick-Login. The server returns a QR Code, or a reference to QR code, depending on the image mode chosen. The process is regularly repeated. Each time a new code is generated. And each code has a life-time of five (5) minutes. Do as follows:

1. Include two javascript files: /Events.js and /QuickLogin.js in your web page. The first pushes events to your page via a websocket connection. It allows the page to become aware of when someone has logged in using the Quick-Login feature. The second javascript file shows the code on the page. You can make this file your own and update it in accordance with your needs.

2. Add a <div> tag to your page, where you want the code to appear. It must have the id attribute set to quickLoginCode, and have two data attributes: data-mode specifies the mode in which the code will be transferred to the web-page. data-purpose contains a purpose string, that will be displayed in the IdApp of the user. You can use the buttons below to experiment using the different modes.

3. Format your Quick-Login with a custom css file. You can customize the /QuickLogin.css file used on this page.

4. Add the domain of the Neuron to the header of the HTML file. This allows the javascript files to know what domain to access for Quick-Login access. Example:

   <meta name="NEURON" content="lab.tagroot.io"/>
   

5. You will have to add Cross-Domain support (CORS Headers) to the page you use, if it lies on another domain.

6. Once the user has signed the Quick Login request from the Neuron, a response in the form of a JSON object (see below) is pushed to the web client using Events.js. The object is sent to the function SignatureReceived, defined in QuickLogin.js (which you can customize), on the browser tab containing the page displaying the QR code.

The following UML diagram displays the flow of messages during a Quick Login using only a web client:

Example, showing how the above login feature was implemented on this page:

JavaScript: /QuickLogin.js
JavaScript: /Events.js
CSS: QuickLogin.css
Neuron: lab.tagroot.io

<div id="quickLoginCode"
     data-mode="image"
     data-purpose="To perform a quick login on lab.tagroot.io, and display your identity information on the page. This request is valid for five (5) minutes."/>

Back-end mode

If it is the back-end that requires the user to log-in, the back-end mode should be used. In this mode, the back-end starts by registering a call-back URL with the Quick-Login service, which responds with a Service ID. This Service ID is sent to the web-client, in an attribute of a <div> tag. The web-client then proceeds by requesting the Quick-Login service to display a QR Code. As in the web client-only mode, this process is repeated regularly, until the user has logged in. Do as follows:

1. The Back-end makes a POST to the Neuron hosting the Quick-Login service, to the resource /QuickLogin. The POST request, must contain a single JSON object, with two field names called service and sessionId, containing the back-end URL to use when someone logs in, and an opaque string that the backend can use to identity the client session being used (or similar). The URI must furthermore use HTTPS. The JSON object would look something like: {"service":"https:...", "sessionId":"..."}.

   

2. Once a Service ID has been generated, it is returned to the back-end in a JSON object with a single field named serviceId. Example: {"serviceId":"..."}.

   

   Note: The Service ID is valid for 5 minutes. You can ping your Service ID by issuing a new POST to the neuron before the time runs out, if you want, this time including a serviceId field with your Service ID. This will restart the timeout-clock giving you 5 new minutes.

   

   The response to the session extension request is the same as a normal session initiation POST, repeating the Session ID sent in the request:

   

3. Now, proceed as in the web-client case (items 1-5), except that in the <div> tag, you will need to add a third data attribute: data-serviceId, containing the same Service ID as the one received from the Back-end URL registration response. Example:

   <div id="quickLoginCode"
   	 data-serviceId="..."
   	 data-mode="image"
   	 data-purpose="To perform a quick login on lab.tagroot.io, and display your identity information on the page. This request is valid for five (5) minutes."/>
   

4. Once the user has signed the Quick Login request from the Neuron, a response in the form of a JSON object (see below) is posted to the URL registered with the Neuron. The resource at this URL must be able to return JSON (null being acceptable JSON). At the same time, an empty event is pushed to the web client using Events.js. The empty string is sent to the function SignatureReceivedBE, defined in QuickLogin.js (which you can customize), on the browser tab containing the page displaying the QR code. This function can be used to refresh the web page, knowing that credentials have been provided to the back-end.

The following UML diagram displays the flow of messages during a Quick Login using a back-end to control user credentials:

Session mode

The session mode is a mix of web client mode, and back-end mode, where the neuron itself is the back-end. The main difference is that the information is not only sent to the client, but also stored in the session on the neuron. To enable this, you need to register a serviceId with the neuron, pointing to itself and the client. This is done by using the QuickLoginServiceId script function, which takes the HTTP Request object as a single parameter. By calling this function from script, and emitting the result in the data-serviceId attribute in the <div/> tag, the quick-login session becomes associated with the current HTTP session. When a user has logged in, the information will be made available in the session variable QuickLoginUser, as well as being pushed to the web client. The session variable name is fixed, to avoid the possibility for malicious or bad code to affect the operation of other parts of the system. Sequence is as follows:

1. Include two javascript files: /Events.js and /QuickLogin.js in your web page. The first pushes events to your page via a websocket connection. It allows the page to become aware of when someone has logged in using the Quick-Login feature. The second javascript file shows the code on the page. You can make this file your own and update it in accordance with your needs.

2. Add a <div> tag to your page, where you want the code to appear. It must have the id attribute set to quickLoginCode, and have two data attributes: data-mode specifies the mode in which the code will be transferred to the web-page. data-purpose contains a purpose string, that will be displayed in the IdApp of the user. Also, add a data-serviceId attribute with the value from calling the script function QuickLoginServiceId(Request). If you want to login to the Agent API in the same process, call the QuickLoginServiceId(Request,Timeout), where Timeout is the number of seconds until the generated Agent API token expires.

3. Format your Quick-Login with a custom css file. You can customize the /QuickLogin.css file used on this page.

4. Add the domain of the Neuron to the header of the HTML file. This allows the javascript files to know what domain to access for Quick-Login access. Example:

   <meta name="NEURON" content="lab.tagroot.io"/>
   

5. You will have to add Cross-Domain support (CORS Headers) to the page you use, if it lies on another domain.

6. Once the user has signed the Quick Login request from the Neuron, a user object is stored in the session variable QuickLoginUser. A response in the form of a JSON object (see below) is also pushed to the web client using Events.js. The object is sent to the function SignatureReceivedBE, defined in QuickLogin.js (which you can customize), on the browser tab containing the page displaying the QR code.

The following UML diagram displays the flow of messages during a Quick Login using session mode:

The Session user variable QuickLoginUser has a similar structure compared to the back-end mode. It has no default privileges.

Example, showing how the above login feature was implemented on this page:

JavaScript: /QuickLogin.js
JavaScript: /Events.js
CSS: QuickLogin.css
Neuron: lab.tagroot.io

<div id="quickLoginCode"
		data-mode="image"
		data-serviceId="{{QuickLoginServiceId(Request)}}"
		data-purpose="To perform a quick login on lab.tagroot.io, and display your identity information on the page. This request is valid for five (5) minutes."/>

Session-proxy mode

The session-proxy mode is a version of session mode, that can be initiated without a web page. It can be used by web servers acting as proxies and that want to integrate Agent API in their services. As there is no web page running on the Neuron® that can call the QuickLoginServiceId(Request,Timeout) function, the session-proxy mode can be used instead. It is initiated the same way as a web client only mode is initiated, with the addition of an agentApiTimeout property in the request, containing the number of seconds a valid Agent API token should be valid. A Service ID will be implicitly created by the Neuron®. It will also be returned in a serviceId property of the response.

Requests made in session-proxy mode must enable cookies, in order to maintain a session over the HTTP interface. Events will be pushed to the client using the web-socket interface as usual, as implemented in the /Events.js and /QuickLogin.js files.

A note on Attachment URLs

Use the Url property to download the attachment directly. It requires Neuro-Foundation-authentication to authorize access. As the Back-End has received approval during the Quick-login, you can also access the recently approved attachment, by using the QuickLogin web service. Access to the attachment via the QuickLogin web service, is done using the BackEndUrl property.

Scaling attachment images

If you use the QuickLogin web service to access attachment images, you can request the neuron to scale the image to fit a given rectangle. To do this, append the width and height of the rectangle, as query parameters on the URL. You do this by appending ?Width=WIDTH&Heihght=HEIGHT to the URL, where you replace WIDTH and HEIGHT with the width and height of the rectangle in which the image should fit.

REST API

Quick-Login has a REST API that can be used to initiate a Quick-Login procedure. If implementing Quick-Login on a web page, it might be easier to use the Web API described above. But if you need to initiate a Quick-Login procedure using other technologies, you can access the REST API directly as well. (This API is used implicitly by the QuickLogin.js` JavaScript file used in the Web API.) The [Back-end mode](#backEndMode) described above also uses this REST API to register a back-end service.

All calls to the Quick-Login API is done to the /QuickLogin resource. This resource supports the GET and POST HTTP methods. POST is used to initiate a Quick-Login procedure or iterate it one step forward, or to register a service or update a service registration. The GET method on the other hand, is used to retrieve QR-codes for an active Quick-Login procedure.

Registering Back-End Service

You register a back-end service, as described above, by sending a POST with the following JSON payload.

You get the following reply:

Updating a Back-End Service registration

You update a back-end service registration, as described above, before it times out, by sending a POST with the following JSON payload.

The response to the session extension request is the same as a normal session initiation POST, repeating the Session ID sent in the request:

Initiating a Quick-Login procedure

Initiating a Quick-Login procedure (or interating the procedure to the next step), is done by sending a POST with the following JSON as payload:

In this request, all properties are required, but serviceId and tab can be empty strings. The mode can be one of the three options described below: text, image, base64. The purpose property is a human-readable text string, that will be sent to the client performing the Quick-Login, and must describe the purpose of the request. If using back-end mode, serviceId must contain the Service ID returned when registering the back-end service. When the client has performed the request, the response will be propagated to the URL provided in this service registration. In session mode, you get the serviceId when you call the QuickLoginServiceId function. This allows the Neuron® to know that it needs to forward responses via the corresponding session. If using either web-client mode, or session mode, the tab property contains the identifier of the current browser tab where the Quick-Login is being displayed. The Tab ID is defined in the JavaScript file /Events.js, and allows the Neuron® to push client events to specific tabs being open and viewing content hosted by the Neuron®. You find the value by referencing the TabID variable defined by the JavaScript.

The response to the request depends on the mode selected in the mode property:

Image mode (image)

The following JSON is returned:

The src property contains an URL that can be placed in an IMG tag to display a QR-code the user can scan to sign the Quick-Login procedure. The width and height properties contain the dimensions of the image. The signUrl contains the URL encoded by the QR-code.

Text mode (text)

The following JSON is returned:

The text property contains an ASCII-encoded string containing block characters, that can be used to display the QR-code on text displays. The signUrl contains the URL encoded by the QR-code.

Base64 mode (base64)

The following JSON is returned:

By using the base64 mode, you avoid making two requests, once to get a new QR code URL, and then get the code image representation. Instead, the QR-code is embedded in the response directly, BASE64-encoded. This is slightly less efficient, than sending the code binary, but limits the need for making two requests. The image can be placed in an IMG tag, if you use the data URI scheme. For that purpose, the Internet Content-Type is also provided in the contentType property. The width and height properties contain the dimensions of the image. The signUrl contains the URL encoded by the QR-code.

Encryption

All calls made to the Quick-Login API MUST be encrypted if the Neuron® has a configured domain name and enabled encryption (i.e. a X.509 Certificate has been generated for the domain). Developer neurons, or internal neurons, that lack a domain name or the ability to generate certificates, allow unencrypted access to the resource.

Identity Information

When a user has logged in, identity information is compiled into a JSON object. In the web client login method, this object is sent in an event (using Events.js) to the SignatureReceived function on the page. In the backend login method, the JSON object is POSTed to the URL registered by the back-end. The JSON object also receives a field named SessionId, allowing the backend to correlate the response with the web client performing the actual login. When the Neuron has received a response from the back-end URL, an empty string event is also pushed to the SignatureReceivedBE function in the corresponding web client (using Events.js), from the Neuron. This allows the web client to refresh its interface as the user has logged in. The back-end software does not need to propagate this event to the client itself.

The following diagram shows the structure of the identity JSON object pushed to the client, or backend. Highlighted fields are only available when pushing the information to back-ends.

Modes

The following modes exist for transferring the code to the web client. You can test them, by pressing the corresponding buttons below: