Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Documentation for Web Widget - Upgrade Keyri FE JS Library #44

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 64 additions & 35 deletions pages/authentication/qr-authentication/keyri-qr-widget.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,36 @@ description: Incorporate Keyri’s QR browser widget into your webpage in a few

# Browser QR Widget Quickstart

1. Serve `KeyriQR.html` (available [here](https://raw.githubusercontent.com/Keyri-Co/library-keyri-connect/main/KeyriQR.html)) from the same origin as your authentication page (e.g., a `/public` directory)
## Demonstration

1. Clone the `keyri-auth-core` repo: `git clone https://github.com/keyri-co/keyri-auth-core`

2. Install everything with `npm install`

3. Run the local server by running `npm run demo`

4. Navigate a browser to `http://localhost/public`

At this point, if everything worked right; you should see a dynamic QR Code.

5. In your browser, open the developer console (`CTRL + SHFT + I`). Click on the first link. This simulates scanning the QR Code with a mobile-app. The two tabs will communicate through the Keyri-API.

6. If everything went to plan, you should get an alert (`hello world`) and the risk-data associated with the transaction in the console.

## Components

1. Serve `iframe.html` (available [here](https://raw.githubusercontent.com/Keyri-Co/keyri-auth-core/main/public/iframe.html)) from the same origin as your authentication page (e.g., a `/public` directory)

2. _RECOMMENDED_: serve everything on your page's origin with the header `X-Frame-Options: SAMEORIGIN` (examples of how to do so [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options#examples))[](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options#examples)

3. Embed an iframe in your authentication page in the desired DOM element with `./KeyriQR.html` as its `src`
3. Embed an iframe in your authentication page in the desired DOM element with `./iframe.html` as its `src`

```html copy {2}
<iframe
src="./KeyriQR.html"
id="qr-frame"
frameborder="0"
height="300"
width="300"
height="500"
width="500"
scrolling="no"
style="border: solid 5px white;"
></iframe>
Expand All @@ -25,38 +42,50 @@ description: Incorporate Keyri’s QR browser widget into your webpage in a few
Now add an event listener to the iframe to listen for messages from it, processing that data however you would like. The example below assumes the mobile app is sending an auth token and places that auth token into local storage. Other options include passing the data into different functions and POSTing to your backend.

```javascript copy
window.addEventListener('message', (evt) => {
// Make sure the event is one from our iFrame
if (evt.data.keyri && evt.data.data && document.location.origin == evt.origin) {
const { data } = evt;

// Since you're sending the data, your situation will differ,
// but for this example, we'll store the data in localStorage and reload
if (!data.error) {
localStorage.token = data.data.token;
document.location.reload();
} else {
// Made up code...
showErrorModal({ title: 'Uh Oh', body: 'Helpful Error Message' });
}
}
});
```
// Import the Events Manager from the library
const { EventManager } = KeyriFrontEnd;
const eventManager = new EventManager(window);

### Local Development
// Set the src of the iframe for the demo
const iframe = document.querySelector("iframe");

To work in a local development environment, add the following query-string to your iframe's `src` attribute (please note that this only works for localhost - any port is fine).
// Change this out with what's on your dashboard
// (n.b. DO NOT PUT IN PRODUCTION! LOCAL TESTING ONLY!)
const appKey = "IT7VrTQ0r4InzsvCNJpRCRpi1qzfgpaj";

`?Host=your.registered.domain.com&appKey=your_app_key`, where `your.registered.domain.com` is the domain with which you registered on (https://app.keyri.com) and `your_app_key` is is the "Application Key" listed under "Setup & Credentials" in the same dashboard. Example as follows:
// Change this out to what you signed up with
// (n.b. DO NOT PUT IN PRODUCTION! LOCAL TESTING ONLY!)
const host = "misc.keyri.com";

```html copy {2}
<iframe
src="./KeyriQR.html?Host=your.registered.domain.com&appKey=your_app_key"
id="qr-frame"
frameborder="0"
height="300"
width="300"
scrolling="no"
style="border: solid 5px white;"
></iframe>
// Set `qsd` (query-string-data) to false if you DO NOT WANT IT IN
// YOUR QR CODE.
//
const qsd = false;

// Demo of what Mobile does at this page here:
const mobileLocation = "http://localhost/public/fakeMobile.html";

// Set the src of the iframe to trigger the QR Load
iframe.src = `./iframe.html?appKey=${appKey}&Host=${host}&qsd=${qsd}&mobile=${mobileLocation}`;

//
// DECRYPTED DATA FROM MOBILE:
//
window.addEventListener("qr_event_session_validate", async (evt) => {
// Proof of concept...
let data = JSON.parse(evt.detail.data);
alert(data.message);
});

//
// RISK METRICS WITH MULTI-LAYERED SIGNATURE PROTECTIONS
//
window.addEventListener("qr_event_risk_data", async (evt) => {
let data = evt.detail.data.information.data;
console.log("RISK DATA", JSON.parse(atob(data)));
});
```

### Production Environment

To work in a production environment, just remove the `Host` and `appKey` from your querystring since you __DO NOT__ want these public.